bug_bunny 3.0.2 → 3.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42bf10dd1d3e749561b43b298e6dda00f9b6a76a40dce49103d1d094faa39948
-  data.tar.gz: 3088ecec60567a95972ed7abc7dff8f6dd9f5019ad6e0a19bb15dcae61e68bb3
+  metadata.gz: 4752202964e5f4382a685a356a31264db3ae51049c42a49d3e5a6602fda10ed1
+  data.tar.gz: 1cb2f414e1fb52560d9a4310fd0679c1a59f86dc072fce6dd385b17006ecc6a0
 SHA512:
-  metadata.gz: ccf976738d355512f3effec2d84a94087c62b41b329516df4cb15ca99034385da216592a7b52acec6aa224708b7c5c272f17dde349a8d5fe88f3903e33ff1122
-  data.tar.gz: 60252a5667d1178b4ac9de5118dd21cfd5538c12c9f69360988f493ffea50c81e4efec2cc08f50570fc9e76c9a57d9bb08c1ef6d75aef4a6b25f995fc765b512
+  metadata.gz: 74af2e635f79d182cfe0fc336a67bf5175ad02729e39b5ddb77fb6bfdde4e3e733f863c78e453160ca6e03ff381dc81f1169a1c9d7be39a116d971638f61d846
+  data.tar.gz: c7da63dcce1cc2f0b77faa253327ddb4eec88866328429e84383172e07be402ff9d9c2ca6a2fbe16e9c0f7762bd8119c17496caa37a4ad35d0be07867e8aa78c

data/CHANGELOG.md

@@ -1,4 +1,19 @@
 # Changelog
+## [3.0.4] - 2026-02-16
+
+### ♻️ Refactoring & Architecture
+* **Middleware Architecture Overhaul:** Refactored the internal middleware stack to follow the **Template Method** pattern (Faraday-style).
+    * **New Base Class:** Introduced `BugBunny::Middleware` to standardize the execution flow (`call`, `app.call`).
+    * **Lifecycle Hooks:** Middlewares can now simply implement `on_request(env)` and/or `on_complete(response)` methods, eliminating the need to manually manage the execution chain.
+    * **Core Middlewares:** Refactored `RaiseError` and `JsonResponse` to use this new pattern, resulting in cleaner and more maintainable code.
+    * This change is **fully backward compatible** and paves the way for future middlewares (Loggers, Tracing, Headers injection).
+
+## [3.0.3] - 2026-02-13
+
+### 🐛 Bug Fixes
+* **Nested Query Serialization:** Fixed an issue where passing nested hashes to `Resource.where` (e.g., `where(q: { service: 'rabbit' })`) produced invalid URL strings (Ruby's `to_s` format) instead of standard HTTP query parameters.
+    * **Resource:** Now uses `Rack::Utils.build_nested_query` to generate correct URLs (e.g., `?q[service]=rabbit`).
+    * **Consumer:** Now uses `Rack::Utils.parse_nested_query` to correctly reconstruct nested hashes from the query string.
 
 ## [3.0.2] - 2026-02-12
 

data/bin_suite.rb

@@ -24,7 +24,7 @@ begin
   response = raw_client.request('test_user/ping', exchange: 'test_exchange', exchange_type: 'topic', routing_key: 'test_user.ping')
   assert(response['body']['message'] == 'Pong!', "Respuesta RPC recibida correctamente")
 rescue => e
-  assert(false, "Error RPC: #{e.message}")
+  assert(false, "Error RPC: #{e.class} - #{e.message}")
 end
 
 # ---------------------------------------------------------
@@ -36,17 +36,26 @@ puts "\n[2] Probando BugBunny::Resource (Estilo Rails)..."
 puts "    -> Buscando usuario ID 123..."
 user = TestUser.find(123)
 
-assert(user.is_a?(TestUser), "El objeto retornado es un TestUser")
-assert(user.name == "Gabriel", "El nombre cargó correctamente")
-assert(user.persisted?, "El objeto figura como persistido")
+if user
+  assert(user.is_a?(TestUser), "El objeto retornado es un TestUser")
+  assert(user.name == "Gabriel", "El nombre cargó correctamente")
+  assert(user.persisted?, "El objeto figura como persistido")
+else
+  assert(false, "No se encontró el usuario (Check worker logs)")
+end
+
 # ---------------------------------------------------------
 # TEST 3: Resource Create (ORM)
 # ---------------------------------------------------------
 puts "\n[3] Probando Resource Creation..."
 puts "    -> Creando usuario nuevo..."
 new_user = TestUser.create(name: "Nuevo User", email: "new@test.com")
-assert(new_user.persisted?, "El usuario se guardó y recibió ID")
-assert(new_user.id.present?, "Tiene ID asignado por el worker (#{new_user.id})")
+if new_user.persisted?
+  assert(new_user.persisted?, "El usuario se guardó y recibió ID")
+  assert(new_user.id.present?, "Tiene ID asignado por el worker (#{new_user.id})")
+else
+  assert(false, "Fallo al crear usuario: #{new_user.errors.full_messages}")
+end
 
 # ---------------------------------------------------------
 # TEST 4: Validaciones Locales
@@ -56,22 +65,42 @@ invalid_user = TestUser.new(email: "sin_nombre@test.com")
 assert(invalid_user.valid? == false, "Usuario sin nombre es inválido")
 assert(invalid_user.errors[:name].any?, "Tiene error en el campo :name")
 
-puts "\n🏁 SUITE FINALIZADA"
-
 # ---------------------------------------------------------
 # TEST 5: Probando Configuración Dinámica (.with)...
 # ---------------------------------------------------------
 puts "\n[5] Probando Configuración Dinámica (.with)..."
 
 # Probamos cambiar el routing key prefix temporalmente
-# El worker escucha 'test_user.*', así que si cambiamos a 'bad_prefix', debería fallar o no encontrar nada
 begin
-  # Forzamos una routing key que no existe para ver si respeta el cambio
+  # Forzamos una routing key que no existe
+  puts "    -> Intentando ruta incorrecta (esperando timeout)..."
   TestUser.with(routing_key: 'ruta.incorrecta').find(123)
-rescue BugBunny::RequestTimeout
-  puts "  ✅ PASS: El override funcionó (timeout esperado en ruta incorrecta)"
+  assert(false, "Debería haber fallado por timeout")
+rescue BugBunny::RequestTimeout, BugBunny::ClientError
+  # Nota: Dependiendo de tu config, puede dar Timeout o 501 si llega a un worker default
+  puts "  ✅ PASS: El override funcionó (timeout o error esperado en ruta incorrecta)"
 end
 
 # Probamos que vuelve a la normalidad
 user = TestUser.find(123)
 assert(user.present?, "  ✅ PASS: La configuración volvió a la normalidad")
+
+# ---------------------------------------------------------
+# TEST 6: Filtrado Complejo (Query String Nested - FIX Rack)
+# ---------------------------------------------------------
+puts "\n[6] Probando Resource.where con filtros anidados (Fix Rack)..."
+
+begin
+  # Esto fallaba antes (generaba string feo en la URL: {:active=>true})
+  # Al usar Rack, esto genera: ?q[active]=true&q[roles][]=admin
+  # No necesitamos que el worker responda algo real, solo que el request SALGA sin explotar URI.
+  TestUser.where(q: { active: true, roles: ['admin'] })
+  puts "  ✅ PASS: .where generó la query anidada correctamente sin errores de URI."
+rescue URI::InvalidURIError => e
+  assert(false, "❌ FAIL: URI Inválida (El fix de Rack no funcionó): #{e.message}")
+rescue => e
+  # Si falla por conexión o 404 está bien, lo importante es que no falle al serializar
+  puts "  ✅ PASS: El request se envió correctamente (aunque el worker responda: #{e.class}). Serialización OK."
+end
+
+puts "\n🏁 SUITE FINALIZADA"

data/lib/bug_bunny/consumer.rb

@@ -4,41 +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.
   #
-  # 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.
+  # 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.
   #
-  # 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.
+  # @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 de RabbitMQ wrapper.
+    # @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] Conexión activa.
-    # @param args [Hash] Argumentos para {#subscribe}.
+    #
+    # @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 el consumidor.
+    # 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 y el procesamiento de mensajes.
+    # 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] 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).
+    # @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)
@@ -58,26 +75,25 @@ module BugBunny
 
     private
 
-    # Procesa un mensaje individual.
+    # Procesa un mensaje individual recibido de la cola.
     #
-    # 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.
+    # Realiza la orquestación completa: Parsing -> Routing -> Ejecución -> Respuesta.
     #
-    # @param delivery_info [Bunny::DeliveryInfo] Metadatos de entrega.
-    # @param properties [Bunny::MessageProperties] Headers y propiedades AMQP.
-    # @param body [String] Payload del mensaje.
+    # @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. Determinar Verbo HTTP (Default: GET)
       http_method = properties.headers ? (properties.headers['x-http-method'] || 'GET') : 'GET'
 
-      # Inferencia de rutas (Router)
+      # 2. Router: Inferencia de Controlador y Acción
       route_info = router_dispatch(http_method, properties.type)
 
       headers = {
@@ -92,55 +108,57 @@ module BugBunny
         reply_to: properties.reply_to
       }
 
-      # Instanciación dinámica del controlador
+      # 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
 
-      # Ejecución del pipeline del controlador
+      # 4. Ejecución del Pipeline (Filtros -> Acción)
       response_payload = controller_class.call(headers: headers, body: body)
 
-      # Respuesta RPC (Éxito)
+      # 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
-      # Caso: Controlador o Acción no existen (404/501)
+      # Error 501/404: El controlador o la acción no existen.
       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
-
+      handle_fatal_error(properties, 501, "Routing Error", e.message)
       session.channel.reject(delivery_info.delivery_tag, false)
 
     rescue StandardError => e
-      # Caso: Crash interno de la aplicación (500)
+      # Error 500: Crash interno de la aplicación.
       BugBunny.configuration.logger.error("[Consumer] Execution Error: #{e.message}")
-
-      # FIX CRÍTICO: Responder con 500 para evitar Timeout
-      if properties.reply_to
-        error_payload = { status: 500, body: { error: "Internal Server Error", detail: e.message } }
-        reply(error_payload, properties.reply_to, properties.correlation_id)
-      end
-
+      handle_fatal_error(properties, 500, "Internal Server Error", e.message)
       session.channel.reject(delivery_info.delivery_tag, false)
     end
 
-    # Simula el Router de Rails.
-    # Convierte Verbo + Path en Controlador + Acción + ID.
+    # Interpreta la URL y el verbo para decidir qué controlador ejecutar.
     #
-    # @return [Hash] { controller, action, id, params }
+    # 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 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?)
-      query_params = uri.query ? CGI.parse(uri.query).transform_values(&:first) : {}
 
+      # --- 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]
 
@@ -152,18 +170,24 @@ module BugBunny
                else id || 'index'
                end
 
-      # Soporte para Custom Member Actions (POST users/1/promote)
+      # Soporte para rutas miembro custom (POST users/1/promote)
       if segments.size >= 3
          id = segments[1]
          action = segments[2]
       end
 
+      # 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 }
     end
 
-    # Envía la respuesta a la cola temporal del cliente (Direct Reply-to).
+    # 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,
@@ -173,11 +197,29 @@ module BugBunny
       )
     end
 
-    # Tarea de fondo para asegurar que la cola sigue existiendo.
+    # 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/middleware/json_response.rb

@@ -1,73 +1,62 @@
 # lib/bug_bunny/middleware/json_response.rb
+# frozen_string_literal: true
+
 require 'json'
+require_relative '../middleware'
 
 module BugBunny
   module Middleware
     # Middleware encargado de parsear automáticamente el cuerpo de la respuesta.
     #
-    # Este middleware intercepta la respuesta proveniente del servicio remoto. Si el `body`
-    # es un String JSON válido, lo convierte a un Hash o Array de Ruby.
-    #
-    # **Integración con Rails:**
-    # Si `ActiveSupport` está cargado en el entorno, convierte los Hashes resultantes
-    # a `HashWithIndifferentAccess`. Esto permite a los desarrolladores acceder a las claves
-    # usando símbolos o strings indistintamente (ej: `body[:id]` o `body['id']`),
-    # comportamiento estándar en Rails.
+    # Convierte strings JSON en Hashes de Ruby. Si está disponible ActiveSupport,
+    # aplica HashWithIndifferentAccess.
     #
-    # @example Uso en la configuración del cliente
-    #   client = BugBunny::Client.new(pool: POOL) do |conn|
-    #     # Se recomienda ponerlo después de RaiseError para tener el body parseado en las excepciones
-    #     conn.use BugBunny::Middleware::RaiseError
-    #     conn.use BugBunny::Middleware::JsonResponse
-    #   end
-    class JsonResponse
-      # Inicializa el middleware.
-      #
-      # @param app [Object] El siguiente middleware o el productor final en el stack.
-      def initialize(app)
-        @app = app
-      end
-
-      # Ejecuta el middleware.
+    # @see BugBunny::Middleware
+    class JsonResponse < BugBunny::Middleware
+      # Hook de ciclo de vida: Ejecutado después de recibir la respuesta.
       #
-      # Invoca al siguiente eslabón (`@app.call`) y espera su retorno.
-      # Una vez recibida la respuesta, procesa el `body` antes de devolverla hacia arriba en la cadena.
+      # Intercepta el body y lo reemplaza por su versión parseada.
       #
-      # @param env [BugBunny::Request] El objeto request actual (el entorno).
-      # @return [Hash] La respuesta con el campo 'body' transformado (si era JSON).
-      def call(env)
-        response = @app.call(env)
-        # Parseamos el body DESPUÉS de recibir la respuesta (Post-processing)
+      # @param response [Hash] La respuesta cruda.
+      # @return [void]
+      def on_complete(response)
         response['body'] = parse_body(response['body'])
-        response
       end
 
+      private
+
       # Intenta convertir el cuerpo de la respuesta a una estructura Ruby nativa.
       #
-      # @param body [String, Hash, Array, nil] El cuerpo original de la respuesta.
-      # @return [Object] El cuerpo parseado (Hash/Array) o el objeto original si falla el parseo.
-      # @api private
+      # @param body [String, Hash, Array, nil] El cuerpo original.
+      # @return [Object] El cuerpo parseado o el original si falla.
       def parse_body(body)
-        return nil if body.nil? || body.empty?
+        return nil if body.nil? || (body.respond_to?(:empty?) && body.empty?)
 
-        # Si ya es un objeto (ej: tests o mocks), lo dejamos pasar, si es String intentamos parsear.
-        parsed = body.is_a?(String) ? JSON.parse(body) : body
+        # Si ya es un objeto (ej: mocks), lo dejamos pasar; si es String, parseamos.
+        parsed = body.is_a?(String) ? safe_json_parse(body) : body
 
         # Rails Magic: Indifferent Access
-        # Si estamos en un entorno Rails, aplicamos la conversión para UX del desarrollador.
-        if defined?(ActiveSupport)
-          if parsed.is_a?(Array)
-            parsed.map! { |e| e.try(:with_indifferent_access) || e }
-          elsif parsed.is_a?(Hash)
-            parsed = parsed.with_indifferent_access
-          end
-        end
+        apply_indifferent_access(parsed)
+      end
 
-        parsed
+      # Parsea JSON de forma segura, retornando el original si falla.
+      def safe_json_parse(json_string)
+        JSON.parse(json_string)
       rescue JSON::ParserError
-        # Si el body no es un JSON válido (ej: texto plano o error del servidor),
-        # devolvemos el string original sin lanzar excepción.
-        body
+        json_string
+      end
+
+      # Aplica ActiveSupport::HashWithIndifferentAccess si es posible.
+      def apply_indifferent_access(data)
+        return data unless defined?(ActiveSupport)
+
+        if data.is_a?(Array)
+          data.map! { |e| e.try(:with_indifferent_access) || e }
+        elsif data.is_a?(Hash)
+          data.with_indifferent_access
+        else
+          data
+        end
       end
     end
   end

data/lib/bug_bunny/middleware/raise_error.rb

@@ -1,61 +1,30 @@
 # lib/bug_bunny/middleware/raise_error.rb
+# frozen_string_literal: true
+
+require_relative '../middleware'
+
 module BugBunny
   module Middleware
     # Middleware que inspecciona el status de la respuesta y lanza excepciones
     # si se encuentran errores (4xx o 5xx).
     #
-    # Mapea los códigos de estado HTTP/AMQP a excepciones específicas de Ruby para facilitar
-    # el manejo de errores mediante `rescue`.
-    #
-    # @note Orden de Middlewares:
-    #   Se recomienda usar este middleware **antes** de `JsonResponse` si deseas que
-    #   la excepción contenga el cuerpo ya parseado (Hash).
-    #
-    # @example Configuración recomendada
-    #   client = BugBunny::Client.new(pool: POOL) do |conn|
-    #     conn.use BugBunny::Middleware::RaiseError   # 1. Verifica errores primero (al salir)
-    #     conn.use BugBunny::Middleware::JsonResponse # 2. Parsea JSON
-    #   end
-    class RaiseError
-      # Inicializa el middleware.
-      # @param app [Object] El siguiente middleware o la aplicación final.
-      def initialize(app)
-        @app = app
-      end
-
-      # Ejecuta el middleware.
-      # Realiza la petición y, al retornar, verifica el estado de la respuesta.
+    # @see BugBunny::Middleware
+    class RaiseError < BugBunny::Middleware
+      # Hook de ciclo de vida: Ejecutado después de recibir la respuesta.
       #
-      # @param env [BugBunny::Request] El objeto request actual.
-      # @return [Hash] La respuesta si el status es exitoso (2xx).
-      # @raise [BugBunny::ClientError] Si el status es 4xx.
-      # @raise [BugBunny::ServerError] Si el status es 5xx.
-      def call(env)
-        response = @app.call(env)
-        on_complete(response)
-        response
-      end
-
       # Verifica el código de estado y lanza la excepción correspondiente.
       #
-      # Mapeo de errores:
-      # * 400 -> {BugBunny::BadRequest}
-      # * 404 -> {BugBunny::NotFound}
-      # * 406 -> {BugBunny::NotAcceptable}
-      # * 408 -> {BugBunny::RequestTimeout}
-      # * 422 -> {BugBunny::UnprocessableEntity}
-      # * 500 -> {BugBunny::InternalServerError}
-      # * Otros 4xx -> {BugBunny::ClientError}
-      #
       # @param response [Hash] El hash de respuesta conteniendo 'status' y 'body'.
+      # @raise [BugBunny::ClientError] Si el status es 4xx.
+      # @raise [BugBunny::ServerError] Si el status es 5xx.
       # @return [void]
       def on_complete(response)
         status = response['status'].to_i
-        body = response['body'] # Nota: Puede ser String o Hash dependiendo de JsonResponse
+        body = response['body']
 
         case status
         when 200..299
-          # OK: No action needed
+          nil # OK
         when 400 then raise BugBunny::BadRequest, body
         when 404 then raise BugBunny::NotFound
         when 406 then raise BugBunny::NotAcceptable
@@ -63,9 +32,18 @@ module BugBunny
         when 422 then raise BugBunny::UnprocessableEntity, body
         when 500 then raise BugBunny::InternalServerError, body
         else
-          raise BugBunny::ClientError, "Unknown error: #{status}" if status >= 400
+          handle_unknown_error(status)
         end
       end
+
+      private
+
+      # Maneja errores 4xx genéricos no mapeados explícitamente.
+      # @param status [Integer] El código de estado HTTP.
+      # @raise [BugBunny::ClientError] Siempre lanza esta excepción.
+      def handle_unknown_error(status)
+        raise BugBunny::ClientError, "Unknown error: #{status}" if status >= 400
+      end
     end
   end
 end

data/lib/bug_bunny/middleware.rb

@@ -0,0 +1,44 @@
+# lib/bug_bunny/middleware.rb
+# frozen_string_literal: true
+
+module BugBunny
+  # Clase base para todos los middlewares de BugBunny.
+  #
+  # Implementa el patrón "Template Method" para estandarizar el flujo de ejecución
+  # de la cadena de responsabilidades (Ida y Vuelta).
+  #
+  # Las subclases deben implementar:
+  # * {#on_request} para modificar la petición antes de enviarla.
+  # * {#on_complete} para modificar la respuesta después de recibirla.
+  #
+  # @abstract Subclase y anula {#on_request} o {#on_complete} para inyectar lógica.
+  class Middleware
+    # @return [Object] El siguiente middleware en la pila o el adaptador final.
+    attr_reader :app
+
+    # Inicializa el middleware.
+    #
+    # @param app [Object] El siguiente eslabón de la cadena.
+    def initialize(app)
+      @app = app
+    end
+
+    # Ejecuta el middleware orquestando los hooks de ciclo de vida.
+    #
+    # 1. Llama a {#on_request} (Ida).
+    # 2. Llama al siguiente eslabón (`@app.call`).
+    # 3. Llama a {#on_complete} (Vuelta).
+    #
+    # @param env [BugBunny::Request] El objeto request (entorno).
+    # @return [Hash] La respuesta final procesada.
+    def call(env)
+      on_request(env) if respond_to?(:on_request)
+
+      response = @app.call(env)
+
+      on_complete(response) if respond_to?(:on_complete)
+
+      response
+    end
+  end
+end

data/lib/bug_bunny/resource.rb

@@ -2,6 +2,7 @@
 require 'active_model'
 require 'active_support/core_ext/string/inflections'
 require 'uri'
+require 'rack/utils'
 
 module BugBunny
   # Clase base para modelos remotos que implementan **Active Record over AMQP (RESTful)**.
@@ -17,7 +18,7 @@ module BugBunny
   #     self.exchange = 'app.topic'
   #     self.resource_name = 'users'
   #     # Opcional: Personalizar la clave raíz del JSON
-  #     self.param_key = 'user_data' 
+  #     self.param_key = 'user_data'
   #   end
   #
   # @example Uso con contexto temporal
@@ -34,16 +35,16 @@ module BugBunny
 
     # @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
 
     # @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
 
@@ -76,21 +77,21 @@ module BugBunny
 
       # @return [ConnectionPool] El pool de conexiones asignado.
       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] El tipo de exchange (default: direct).
       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.
       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'`.
       #
@@ -122,7 +123,7 @@ module BugBunny
       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
@@ -137,7 +138,7 @@ module BugBunny
         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" }
         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
@@ -150,7 +151,7 @@ module BugBunny
           ScopeProxy.new(self, keys, old_values)
         end
       end
-      
+
       # Proxy para permitir encadenamiento: User.with(...).find(1)
       class ScopeProxy < BasicObject
         def initialize(target, keys, old_values); @target = target; @keys = keys; @old_values = old_values; end
@@ -179,13 +180,14 @@ module BugBunny
       def where(filters = {})
         rk = calculate_routing_key
         path = resource_name
-        path += "?#{URI.encode_www_form(filters)}" if filters.present?
+
+        # 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)
 
         return [] unless response['body'].is_a?(Array)
         response['body'].map do |attrs|
-          # Al instanciar aquí, se captura el contexto si estamos dentro de un .with
           inst = new(attrs)
           inst.persisted = true
           inst.send(:clear_changes_information)
@@ -204,7 +206,7 @@ module BugBunny
         response = bug_bunny_client.request(path, method: :get, exchange: current_exchange, exchange_type: current_exchange_type, routing_key: rk)
 
         return nil if response.nil? || response['status'] == 404
-        
+
         attributes = response['body']
         return nil unless attributes.is_a?(Hash)
 
@@ -235,12 +237,12 @@ module BugBunny
     def initialize(attributes = {})
       @remote_attributes = {}.with_indifferent_access
       @persisted = false
-      
+
       # === CAPTURA DE CONTEXTO ===
       @routing_key = self.class.thread_config(:routing_key)
       @exchange = self.class.thread_config(:exchange)
       @exchange_type = self.class.thread_config(:exchange_type)
-      
+
       assign_attributes(attributes)
       super()
     end
@@ -269,7 +271,7 @@ module BugBunny
       return if new_attributes.nil?
       new_attributes.each { |k, v| public_send("#{k}=", v) }
     end
-    
+
     def update(attributes)
       assign_attributes(attributes)
       save
@@ -325,10 +327,10 @@ module BugBunny
       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 }

data/lib/bug_bunny/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BugBunny
-  VERSION = "3.0.2"
+  VERSION = "3.0.4"
 end

data/lib/bug_bunny.rb

@@ -13,6 +13,7 @@ require_relative 'bug_bunny/resource'
 require_relative 'bug_bunny/rabbit'
 require_relative 'bug_bunny/consumer'
 require_relative 'bug_bunny/controller'
+require_relative 'bug_bunny/middleware'
 
 require_relative 'bug_bunny/middleware/stack'
 require_relative 'bug_bunny/middleware/raise_error'

data/test_resource.rb

@@ -1,22 +1,19 @@
 require_relative 'test_helper'
 
 class TestUser < BugBunny::Resource
-  # Se decide qué pool usar en cada petición
-  self.connection_pool = -> {
-    nil || TEST_POOL
-  }
-
-  # El exchange cambia según el entorno
-  self.exchange = -> {
-    ENV['IS_STAGING'] ? 'test_exchange' : 'test_exchange'
-  }
+  # Configuración del Pool
+  self.connection_pool = -> { nil || TEST_POOL }
 
+  # Configuración del Exchange
+  self.exchange = -> { ENV['IS_STAGING'] ? 'test_exchange' : 'test_exchange' }
   self.exchange_type = 'topic'
-  self.routing_key_prefix = 'test_user'
 
-  attribute :id, :integer
-  attribute :name, :string
-  attribute :email, :string
+  # ACTUALIZADO v3.0: Usamos resource_name
+  self.resource_name = 'test_users'
+
+  # ELIMINADO: attribute :id, :integer (Causa crash en v3)
+  # ELIMINADO: attribute :name, :string (Causa crash en v3)
 
+  # Las validaciones siguen funcionando igual
   validates :name, presence: true
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bug_bunny
 version: !ruby/object:Gem::Version
-  version: 3.0.2
+  version: 3.0.4
 platform: ruby
 authors:
 - gabix
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-02-12 00:00:00.000000000 Z
+date: 2026-02-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bunny
@@ -200,6 +200,7 @@ files:
 - lib/bug_bunny/consumer.rb
 - lib/bug_bunny/controller.rb
 - lib/bug_bunny/exception.rb
+- lib/bug_bunny/middleware.rb
 - lib/bug_bunny/middleware/json_response.rb
 - lib/bug_bunny/middleware/raise_error.rb
 - lib/bug_bunny/middleware/stack.rb