bug_bunny 3.1.6 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7fec9f487076682121e6d8586e44fe9d70f380bd809fb46014265105421a0d8f
-  data.tar.gz: e847fc6f1943f9921f2250a46a20bd6f76b20736812fcbf6bfc437ab49a8a30c
+  metadata.gz: b06b89852caa37c57d4db098d7f2f51f6d6f7361898ce5fc3484ad81e31068fd
+  data.tar.gz: cc53173b422e52e54e3a3a8af54676f6a954279ab81847335be3b37a5251b882
 SHA512:
-  metadata.gz: 199faaa596f52cc1c192259e8fe3e7da95152d117db9ded079051bebdff985793e63acde11cb8ceed5e0e216d6934ff35056993947609f2818d8429f524a789a
-  data.tar.gz: dfefdd78b4597f90dc059ef07d7423dda86d2630cdab409c514941708cc539d174a763d1a6e18c918dee7058d25c0a996aac0bb52f1b440573b42480e723e284
+  metadata.gz: 6643abb20472bea870426d694d3481c6ced6bd1bf2d0a26e6cbc0526f60050b016de265785611cd4e7046304cc88058104845172d676475be1dc7c6b6ad79d10
+  data.tar.gz: 3f60029f149d765752616323fcf53ce9406ca80e3cffeeaf008bf8a54daac0f06366495081629b1f22127e6bc171080a5946f89341d5cebb5929596d70275bc1

data/CHANGELOG.md

@@ -1,4 +1,21 @@
 # Changelog
+## [4.0.0] - 2026-03-02
+
+### ⚠ Breaking Changes
+* **Declarative Routing (Rails-style):** El enrutamiento "mágico" y heurístico del Consumer ha sido reemplazado por un motor de enrutamiento explícito y estricto.
+  * Ahora es **obligatorio** definir un mapa de rutas usando el DSL `BugBunny.routes.draw` (típicamente en un inicializador como `config/initializers/bug_bunny_routes.rb`).
+  * Los mensajes entrantes cuyas rutas no estén explícitamente declaradas serán rechazados inmediatamente con un error `404 Not Found`.
+
+### 🚀 New Features & Architecture
+* **Advanced Routing DSL:** Se construyó un motor de enrutamiento completo y robusto inspirado en `ActionDispatch::Routing` de Rails.
+  * **Smart Route Parameters:** Compilación de rutas a expresiones regulares, permitiendo la extracción nativa de parámetros dinámicos desde la URL (ej. `get 'clusters/:cluster_id/nodes/:id/metrics'`). Estos se inyectan automáticamente en el hash `params` del Controlador.
+  * **Resource Macros & Filtering:** Introducción del macro `resources :name` para generar endpoints CRUD estándar. Ahora soporta filtrado granular de acciones utilizando las opciones `only:` y `except:`.
+  * **Nested Scopes (Member/Collection):** Soporte total para bloques anidados `member do ... end` y `collection do ... end` dentro de los recursos, permitiendo definir rutas complejas infiriendo automáticamente el controlador destino y la inyección del `:id`.
+
+### 🛡️ Security & Observability
+* **Strict Instantiation (RCE Prevention):** Al requerir que todas las rutas sean declaradas explícitamente por el desarrollador, se elimina por completo el vector de ataque que permitía intentar instanciar clases arbitrarias de Ruby manipulando el header `type`.
+* **Enhanced Routing Logs:** El Consumer ahora emite un log de nivel `DEBUG` (marcado con 🎯) que confirma de manera transparente exactamente qué Controlador y Acción se resolvieron al evaluar la petición contra el mapa de rutas.
+
 ## [3.1.6] - 2026-02-27
 
 ### 🐛 Bug Fixes & Router Improvements

data/README.md

@@ -4,7 +4,7 @@
 
 **Active Record over AMQP.**
 
-BugBunny transforma la complejidad de la mensajería asíncrona (RabbitMQ) en una arquitectura **RESTful familiar** para desarrolladores Rails. Envía mensajes como si estuvieras usando Active Record y procésalos como si fueran Controladores de Rails.
+BugBunny transforma la complejidad de la mensajería asíncrona (RabbitMQ) en una arquitectura **RESTful familiar** para desarrolladores Rails. Envía mensajes como si estuvieras usando Active Record y procésalos como si fueran Controladores de Rails, apoyado por un potente motor de enrutamiento declarativo.
 
 ---
 
@@ -12,14 +12,14 @@ BugBunny transforma la complejidad de la mensajería asíncrona (RabbitMQ) en un
 - [Introducción: La Filosofía](#-introducción-la-filosofía)
 - [Instalación](#-instalación)
 - [Configuración Inicial](#-configuración-inicial)
-- [Configuración de Infraestructura en Cascada](#-configuración-de-infraestructura-en-cascada-nuevo-v31)
+- [Configuración de Infraestructura en Cascada](#-configuración-de-infraestructura-en-cascada)
 - [Modo Cliente: Recursos (ORM)](#-modo-cliente-recursos-orm)
     - [Definición y Atributos](#1-definición-y-atributos-híbridos)
     - [CRUD y Consultas](#2-crud-y-consultas-restful)
     - [Contexto Dinámico (.with)](#3-contexto-dinámico-with)
     - [Client Middleware](#4-client-middleware-interceptores)
 - [Modo Servidor: Controladores](#-modo-servidor-controladores)
-    - [Ruteo Inteligente](#1-ruteo-inteligente)
+    - [Ruteo Declarativo (Rutas)](#1-ruteo-declarativo-rutas)
     - [El Controlador](#2-el-controlador)
     - [Manejo de Errores](#3-manejo-de-errores-declarativo)
 - [Observabilidad y Tracing](#-observabilidad-y-tracing)
@@ -33,7 +33,7 @@ En lugar de pensar en "Exchanges" y "Queues", BugBunny inyecta verbos HTTP (`GET
 
 * **Tu código (Cliente):** `User.create(name: 'Gabi')`
 * **Protocolo (BugBunny):** Envía `POST /users` (Header `type: users`) vía RabbitMQ.
-* **Worker (Servidor):** Recibe el mensaje y ejecuta `UsersController#create`.
+* **Worker (Servidor):** Recibe el mensaje, evalúa tu mapa de rutas y ejecuta `UsersController#create`.
 
 ---
 
@@ -42,7 +42,7 @@ En lugar de pensar en "Exchanges" y "Queues", BugBunny inyecta verbos HTTP (`GET
 Agrega la gema a tu `Gemfile`:
 
 ```ruby
-gem 'bug_bunny', '~> 3.1'
+gem 'bug_bunny', '~> 4.0'
 ```
 
 Ejecuta el bundle e instala los archivos base:
@@ -95,9 +95,9 @@ BugBunny::Resource.connection_pool = BUG_BUNNY_POOL
 
 ---
 
-## 🏗️ Configuración de Infraestructura en Cascada (Nuevo v3.1)
+## 🏗️ Configuración de Infraestructura en Cascada
 
-BugBunny v3.1 introduce un sistema de configuración jerárquico para los parámetros de RabbitMQ (como la durabilidad de Exchanges y Colas). Las opciones se resuelven en el siguiente orden de prioridad:
+BugBunny utiliza un sistema de configuración jerárquico para los parámetros de RabbitMQ (como la durabilidad de Exchanges y Colas). Las opciones se resuelven en el siguiente orden de prioridad:
 
 1.  **Defaults de la Gema:** Rápidos y efímeros (`durable: false`).
 2.  **Configuración Global:** Definida en el inicializador para todo el entorno.
@@ -124,7 +124,7 @@ end
 Los recursos son proxies de servicios remotos. Heredan de `BugBunny::Resource`.
 
 ### 1. Definición y Atributos Híbridos
-BugBunny v3 es **Schema-less**. Soporta atributos tipados (ActiveModel) y dinámicos simultáneamente, además de definir su propia infraestructura.
+BugBunny es **Schema-less**. Soporta atributos tipados (ActiveModel) y dinámicos simultáneamente, además de definir su propia infraestructura.
 
 ```ruby
 # app/models/manager/service.rb
@@ -188,7 +188,7 @@ Manager::Service.with(
 ```
 
 ### 4. Client Middleware (Interceptores)
-Intercepta peticiones de ida y respuestas de vuelta en la arquitectura del cliente. 
+Intercepta peticiones de ida y respuestas de vuelta en la arquitectura del cliente.
 
 **Middlewares Incluidos (Built-ins)**
 Si usas `BugBunny::Resource`, el manejo de JSON y de errores ya está integrado automáticamente. Pero si utilizas el cliente manual (`BugBunny::Client`), puedes inyectar los middlewares incluidos para no tener que parsear respuestas manualmente:
@@ -251,22 +251,44 @@ BugBunny::Middleware::RaiseError.prepend(CustomBugBunnyErrors)
 
 ## 📡 Modo Servidor: Controladores
 
-BugBunny implementa un **Router** que despacha mensajes a controladores basándose en el header `type` (URL) y `x-http-method`.
+A partir de BugBunny v4, el enrutamiento es **declarativo** y explícito, al igual que en Rails. Se utiliza un archivo de rutas centralizado para mapear los mensajes AMQP entrantes a los Controladores adecuados.
 
-### 1. Ruteo Inteligente
-El consumidor infiere automáticamente la acción:
+### 1. Ruteo Declarativo (Rutas)
+Crea un inicializador en tu aplicación (ej. `config/initializers/bug_bunny_routes.rb`) para definir tu mapa de rutas. BugBunny usará este DSL para extraer automáticamente parámetros dinámicos de las URLs.
 
-| Verbo AMQP | Path (Header `type`) | Controlador | Acción |
-| :--- | :--- | :--- | :--- |
-| `GET` | `services` | `ServicesController` | `index` |
-| `GET` | `services/123` | `ServicesController` | `show` |
-| `POST` | `services` | `ServicesController` | `create` |
-| `PUT` | `services/123` | `ServicesController` | `update` |
-| `DELETE` | `services/123` | `ServicesController` | `destroy` |
-| `POST` | `services/123/restart` | `ServicesController` | `restart` (Custom) |
+```ruby
+# config/initializers/bug_bunny_routes.rb
+
+BugBunny.routes.draw do
+  # 1. Colecciones Básicas y Filtrado
+  # Genera rutas para index, show y update únicamente
+  resources :services, only: [:index, :show, :update]
+
+  # 2. Rutas Anidadas (Member y Collection)
+  resources :nodes, except: [:create, :destroy] do
+    # Member inyecta el parámetro :id (ej. PUT nodes/:id/drain)
+    member do
+      put :drain
+      post :restart
+    end
+
+    # Collection opera sobre el conjunto (ej. GET nodes/stats)
+    collection do
+      get :stats
+    end
+  end
+
+  # 3. Rutas estáticas (Colecciones o Acciones Custom)
+  get 'health_checks/up', to: 'health_checks#up'
+
+  # 4. Extracción automática de variables dinámicas profundas
+  get 'api/v1/clusters/:cluster_id/nodes/:node_id/metrics', to: 'api/v1/metrics#show'
+end
+```
 
 ### 2. El Controlador
 Ubicación: `app/rabbit/controllers/`.
+Los parámetros declarados en el archivo de rutas (como `:id` o `:cluster_id`) estarán disponibles automáticamente dentro del hash `params` de tu controlador.
 
 ```ruby
 class ServicesController < BugBunny::Controller
@@ -279,7 +301,7 @@ class ServicesController < BugBunny::Controller
   end
 
   def create
-    # BugBunny envuelve los params automáticamente (param_key)
+    # BugBunny envuelve los params automáticamente basándose en el resource_name
     # params[:service] => { name: '...', replicas: ... }
     if Service.create(params[:service])
       render status: 201, json: { status: 'created' }
@@ -291,7 +313,7 @@ class ServicesController < BugBunny::Controller
   private
 
   def set_service
-    # params[:id] se extrae del Path
+    # params[:id] es extraído e inyectado por el BugBunny.routes
     @service = Service.find(params[:id])
   end
 end
@@ -317,16 +339,14 @@ end
 
 ## 🔎 Observabilidad y Tracing
 
-> **Novedad v3.1:** BugBunny implementa Distributed Tracing nativo.
-
-El `correlation_id` se mantiene intacto a través de toda la cadena: `Producer -> RabbitMQ -> Consumer -> Controller`.
+BugBunny implementa Distributed Tracing nativo. El `correlation_id` se mantiene intacto a través de toda la cadena: `Producer -> RabbitMQ -> Consumer -> Controller`.
 
 ### 1. Logs Automáticos (Consumer)
 No requiere configuración. El worker envuelve la ejecución en bloques de log etiquetados con el UUID.
 
 ```text
-[d41d8cd9...] [Consumer] Listening on queue...
-[d41d8cd9...] [API] Processing ServicesController#create...
+[d41d8cd9...] [BugBunny::Consumer] 📥 Received PUT "/nodes/4bv445vgc158hk" | RK: 'dbu55...'
+[d41d8cd9...] [BugBunny::Consumer] 🎯 Routed to Rabbit::Controllers::NodesController#drain
 ```
 
 ### 2. Logs de Negocio (Controller)
@@ -378,7 +398,7 @@ Para máxima velocidad, BugBunny usa `amq.rabbitmq.reply-to`.
 * **Recomendación:** Diseña tus acciones RPC (`POST`, `PUT`) para que sean **idempotentes** (seguras de reintentar ante un timeout).
 
 ### Seguridad
-El Router incluye protecciones contra **Remote Code Execution (RCE)**. Verifica estrictamente que la clase instanciada herede de `BugBunny::Controller` antes de ejecutarla, impidiendo la inyección de clases arbitrarias de Ruby vía el header `type`.
+El Router incluye protecciones contra **Remote Code Execution (RCE)**. El Consumer verifica estrictamente que el Controlador resuelto a través del archivo de rutas herede de `BugBunny::Controller` antes de ejecutarla, impidiendo la inyección de clases arbitrarias. Además, las llamadas a rutas no registradas fallan rápido con un `404 Not Found`.
 
 ### Health Checks en Docker Swarm / Kubernetes
 Dado que un Worker se ejecuta en segundo plano sin exponer un servidor web tradicional, orquestadores como Docker Swarm o Kubernetes no pueden usar un endpoint HTTP para verificar si el proceso está saludable.

data/lib/bug_bunny/consumer.rb

@@ -15,7 +15,7 @@ module BugBunny
   # 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.
+  # 3. Consultar el mapa global `BugBunny.routes` para enrutar el mensaje a un Controlador.
   # 4. Gestionar el ciclo de respuesta RPC (Request-Response) para evitar timeouts en el cliente.
   #
   # @example Suscripción manual
@@ -99,16 +99,16 @@ module BugBunny
 
     private
 
-    # Procesa un mensaje individual recibido de la cola.
+    # Procesa un mensaje individual recibido de la cola orquestando el ruteo declarativo.
     #
-    # Realiza la orquestación completa: Parsing -> Routing -> Ejecución -> Respuesta.
+    # Realiza la orquestación completa: Parsing -> Reconocimiento de Ruta -> 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)
-      # 1. Validación de Headers
+      # 1. Validación de Headers (URL path)
       path = properties.type || (properties.headers && properties.headers['path'])
 
       if path.nil? || path.empty?
@@ -119,142 +119,91 @@ module BugBunny
 
       # 2. Recuperación Robusta del Verbo HTTP
       headers_hash = properties.headers || {}
-      http_method = headers_hash['x-http-method'] || headers_hash['method'] || 'GET'
+      http_method = (headers_hash['x-http-method'] || headers_hash['method'] || 'GET').to_s.upcase
 
-      # 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.info("[BugBunny::Consumer] 📥 Received #{http_method} \"/#{path}\" | RK: '#{delivery_info.routing_key}'")
       BugBunny.configuration.logger.debug("[BugBunny::Consumer] 📦 Body: #{body.truncate(200)}")
 
-      request_metadata = {
-        type: path,
-        http_method: http_method,
-        controller: route_info[:controller],
-        action: route_info[:action],
-        id: route_info[:id],
-        query_params: route_info[:params],
-        content_type: properties.content_type,
-        correlation_id: properties.correlation_id,
-        reply_to: properties.reply_to
-      }.merge(properties.headers)
+      # ===================================================================
+      # 3. Ruteo Declarativo
+      # ===================================================================
+      uri = URI.parse("http://dummy/#{path}")
 
-      # 4. Instanciación Dinámica del Controlador
-      # Utilizamos el namespace configurado en lugar de hardcodear "Rabbit::Controllers"
-      begin
-        namespace = BugBunny.configuration.controller_namespace
-        controller_name = route_info[:controller].camelize
+      # Extraemos query params (ej. /nodes?status=active)
+      query_params = uri.query ? Rack::Utils.parse_nested_query(uri.query) : {}
+      if defined?(ActiveSupport::HashWithIndifferentAccess)
+        query_params = query_params.with_indifferent_access
+      end
 
-        # Construcción: "Messaging::Handlers" + "::" + "Users"
-        controller_class_name = "#{namespace}::#{controller_name}Controller"
+      # Le preguntamos al motor de rutas global quién debe manejar esto
+      route_info = BugBunny.routes.recognize(http_method, uri.path)
 
-        controller_class = controller_class_name.constantize
+      if route_info.nil?
+        BugBunny.configuration.logger.warn("[BugBunny::Consumer] ⚠️  No route matches [#{http_method}] \"/#{uri.path}\"")
+        handle_fatal_error(properties, 404, "Not Found", "No route matches [#{http_method}] \"/#{uri.path}\"")
+        session.channel.reject(delivery_info.delivery_tag, false)
+        return
+      end
 
-        unless controller_class < BugBunny::Controller
-          raise BugBunny::SecurityError, "Class #{controller_class} is not a valid BugBunny Controller"
-        end
-      rescue NameError => _e
-        BugBunny.configuration.logger.warn("[BugBunny::Consumer] ⚠️  Controller not found: #{controller_class_name} (Path: #{path})")
+      # Fusionamos los parámetros extraídos de la URL (ej. :id) con los query_params
+      final_params = query_params.merge(route_info[:params])
+
+      # ===================================================================
+      # 4. Instanciación del Controlador
+      # ===================================================================
+      namespace = BugBunny.configuration.controller_namespace
+      controller_name = route_info[:controller].camelize
+      controller_class_name = "#{namespace}::#{controller_name}Controller"
+
+      begin
+        controller_class = controller_class_name.constantize
+      rescue NameError
+        BugBunny.configuration.logger.warn("[BugBunny::Consumer] ⚠️  Controller class not found: #{controller_class_name}")
         handle_fatal_error(properties, 404, "Not Found", "Controller #{controller_class_name} not found")
         session.channel.reject(delivery_info.delivery_tag, false)
         return
       end
 
-      # 5. Ejecución del Pipeline (Middleware + Acción)
+      # Verificación estricta de Seguridad (RCE Prevention)
+      unless controller_class < BugBunny::Controller
+        BugBunny.configuration.logger.error("[BugBunny::Consumer] ⛔ Security Alert: #{controller_class} is not a valid BugBunny Controller")
+        handle_fatal_error(properties, 403, "Forbidden", "Invalid Controller Class")
+        session.channel.reject(delivery_info.delivery_tag, false)
+        return
+      end
+
+      BugBunny.configuration.logger.debug("[BugBunny::Consumer] 🎯 Routed to #{controller_class_name}##{route_info[:action]}")
+
+      request_metadata = {
+        type: path,
+        http_method: http_method,
+        controller: route_info[:controller],
+        action: route_info[:action],
+        id: final_params['id'] || final_params[:id],
+        query_params: final_params,
+        content_type: properties.content_type,
+        correlation_id: properties.correlation_id,
+        reply_to: properties.reply_to
+      }.merge(headers_hash)
+
+      # ===================================================================
+      # 5. Ejecución y Respuesta
+      # ===================================================================
       response_payload = controller_class.call(headers: request_metadata, body: body)
 
-      # 6. Respuesta RPC
       if properties.reply_to
         reply(response_payload, properties.reply_to, properties.correlation_id)
       end
 
-      # 7. Acknowledge
       session.channel.ack(delivery_info.delivery_tag)
 
     rescue StandardError => e
       BugBunny.configuration.logger.error("[BugBunny::Consumer] 💥 Execution Error (#{e.class}): #{e.message}")
+      BugBunny.configuration.logger.debug(e.backtrace.join("\n"))
       handle_fatal_error(properties, 500, "Internal Server Error", e.message)
       session.channel.reject(delivery_info.delivery_tag, false)
     end
 
-    # Interpreta la URL y el verbo para decidir qué controlador ejecutar.
-    #
-    # Implementa un Router Heurístico que soporta namespaces y acciones custom
-    # buscando dinámicamente el ID en la ruta mediante Regex y Fallback Semántico.
-    #
-    # @param method [String] Verbo HTTP (GET, POST, etc).
-    # @param path [String] URL virtual del recurso (ej: 'foo/bar/algo/13/test').
-    # @return [Hash] Estructura con keys {:controller, :action, :id, :params}.
-    def router_dispatch(method, path)
-      uri = URI.parse("http://dummy/#{path}")
-      segments = uri.path.split('/').reject(&:empty?)
-
-      query_params = uri.query ? Rack::Utils.parse_nested_query(uri.query) : {}
-      if defined?(ActiveSupport::HashWithIndifferentAccess)
-        query_params = query_params.with_indifferent_access
-      end
-
-      # 1. Acción Built-in: Health Check Global (/up o /api/up)
-      if segments.last == 'up' && method.to_s.upcase == 'GET'
-        ctrl = segments.size > 1 ? segments[0...-1].join('/') : 'application'
-        return { controller: ctrl, action: 'up', id: nil, params: query_params }
-      end
-
-      # 2. Búsqueda dinámica del ID (Heurística por Regex)
-      # Patrón: Enteros, UUIDs, o Hashes largos (Docker Swarm 25 chars, Mongo 24 chars)
-      id_pattern = /^(?:\d+|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[a-zA-Z0-9_-]{20,})$/
-
-      # FIX: Usamos rindex (de derecha a izquierda) para evitar falsos positivos con namespaces como 'v1'
-      id_index = segments.rindex { |s| s.match?(id_pattern) }
-
-      # 3. Fallback Semántico Posicional
-      # Si el regex no detectó el ID (ej: ID corto como "node-1"), pero la semántica HTTP
-      # indica que es una operación singular (PUT/DELETE/GET), asumimos que el último segmento es el ID.
-      if id_index.nil? && segments.size >= 2
-        last_segment = segments.last
-        method_up = method.to_s.upcase
-
-        is_member_verb = %w[PUT PATCH DELETE].include?(method_up)
-        # En GET, nos aseguramos que la última palabra no sea una acción estándar de REST
-        is_get_member = method_up == 'GET' && !%w[index new edit up action].include?(last_segment)
-
-        if is_member_verb || is_get_member
-          # Si tiene 3 o más segmentos (ej. nodes/node-1/stats), el ID no está al final.
-          # Este fallback asume que para IDs raros, el formato clásico es recurso/id
-          id_index = segments.size - 1
-        end
-      end
-
-      # 4. Asignación de variables según escenario
-      if id_index
-        # ESCENARIO A: Ruta Miembro (ej. nodes/4bv445vgc158hk4twlxmdjo0v/stats)
-        controller_name = segments[0...id_index].join('/')
-        id = segments[id_index]
-        action = segments[id_index + 1] # Puede ser nil si no hay acción extra al final
-      else
-        # ESCENARIO B: Ruta Colección (ej. api/v1/nodes)
-        controller_name = segments.join('/')
-        id = nil
-        action = nil
-      end
-
-      # 5. Inferimos la acción clásica de Rails si no hay una explícita
-      unless action
-        action = case method.to_s.upcase
-                 when 'GET' then id ? 'show' : 'index'
-                 when 'POST' then 'create'
-                 when 'PUT', 'PATCH' then 'update'
-                 when 'DELETE' then 'destroy'
-                 else id ? 'show' : 'index'
-                 end
-      end
-
-      # 6. Inyectamos el ID en los parámetros para fácil acceso en el Controlador
-      query_params['id'] = id if id
-
-      { 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: ... }).

data/lib/bug_bunny/routing/route.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module BugBunny
+  module Routing
+    # Representa una ruta individual dentro del mapa de rutas de BugBunny.
+    #
+    # Esta clase se encarga de compilar un patrón de URL (ej. 'users/:id') en una
+    # Expresión Regular capaz de evaluar coincidencias y extraer los parámetros
+    # dinámicos nombrados de forma automática.
+    class Route
+      # @return [String] El verbo HTTP de la ruta (GET, POST, PUT, DELETE).
+      attr_reader :http_method
+
+      # @return [String] El patrón original de la ruta (ej. 'nodes/:node_id/metrics').
+      attr_reader :path_pattern
+
+      # @return [String] El nombre del controlador en formato snake_case (ej. 'api/v1/metrics').
+      attr_reader :controller
+
+      # @return [String] El nombre de la acción a ejecutar (ej. 'show').
+      attr_reader :action
+
+      # Inicializa una nueva Ruta compilando su Expresión Regular.
+      #
+      # @param http_method [String, Symbol] Verbo HTTP (ej. :get, 'POST').
+      # @param path_pattern [String] Patrón de la URL. Los parámetros dinámicos deben iniciar con ':' (ej. 'users/:id').
+      # @param to [String] Destino en formato 'controlador#accion' (ej. 'users#show').
+      # @raise [ArgumentError] Si el formato del destino `to` es inválido.
+      def initialize(http_method, path_pattern, to:)
+        @http_method = http_method.to_s.upcase
+        @path_pattern = normalize_path(path_pattern)
+
+        parse_destination!(to)
+        compile_regex!
+      end
+
+      # Evalúa si una petición entrante coincide con esta ruta.
+      #
+      # @param method [String] El verbo HTTP entrante.
+      # @param path [String] La URL entrante a evaluar.
+      # @return [Boolean] `true` si hace match, `false` en caso contrario.
+      def match?(method, path)
+        return false unless @http_method == method.to_s.upcase
+
+        normalized_path = normalize_path(path)
+        @regex.match?(normalized_path)
+      end
+
+      # Extrae los parámetros dinámicos de una URL que hizo coincidencia con el patrón.
+      #
+      # @param path [String] La URL entrante (ej. 'users/123').
+      # @return [Hash] Diccionario con las variables extraídas (ej. { 'id' => '123' }).
+      # @example
+      #   route = Route.new('GET', 'users/:id', to: 'users#show')
+      #   route.extract_params('users/42') # => { 'id' => '42' }
+      def extract_params(path)
+        normalized_path = normalize_path(path)
+        match_data = @regex.match(normalized_path)
+
+        return {} unless match_data
+
+        # match_data.named_captures devuelve un Hash con las variables que definimos en la Regex
+        match_data.named_captures
+      end
+
+      private
+
+      # Elimina las barras '/' al principio y al final para evitar problemas de formato.
+      #
+      # @param path [String] URL cruda.
+      # @return [String] URL normalizada.
+      def normalize_path(path)
+        path.to_s.gsub(%r{^/|/$}, '')
+      end
+
+      # Parsea el string 'controlador#accion' y lo asigna a las variables de instancia.
+      #
+      # @param destination [String] El destino declarado por el usuario.
+      def parse_destination!(destination)
+        parts = destination.split('#')
+        if parts.size != 2
+          raise ArgumentError, "Destino inválido: '#{destination}'. Debe seguir el formato 'controlador#accion'."
+        end
+
+        @controller = parts[0]
+        @action = parts[1]
+      end
+
+      # Transforma el string 'users/:id' en una Regex de Ruby con "Named Captures".
+      # Reemplaza los :param por (?<param>[^/]+) que captura todo hasta la siguiente barra.
+      def compile_regex!
+        # Si la ruta es estática ('swarm/info'), la regex simplemente será /^swarm\/info$/
+        # Si tiene variables ('nodes/:id'), convertimos el :id en un grupo de captura.
+        pattern = @path_pattern.gsub(/:([a-zA-Z0-9_]+)/) do |match|
+          param_name = match.delete(':')
+          "(?<#{param_name}>[^/]+)"
+        end
+
+        @regex = Regexp.new("^#{pattern}$")
+      end
+    end
+  end
+end

data/lib/bug_bunny/routing/route_set.rb

@@ -0,0 +1,268 @@
+# frozen_string_literal: true
+
+require_relative 'route'
+
+module BugBunny
+  module Routing
+    # Gestiona la colección de rutas de la aplicación y expone el DSL de configuración.
+    #
+    # Actúa como el motor principal del enrutador. Permite definir rutas de forma
+    # declarativa (estilo Rails) e incluye macros convenientes como `resources`,
+    # soportando bloques anidados `member` y `collection`.
+    #
+    # @example Configuración del DSL en un inicializador
+    #   route_set = RouteSet.new
+    #   route_set.draw do
+    #     get 'ping', to: 'health#ping'
+    #
+    #     resources :nodes, except: [:create, :destroy] do
+    #       member do
+    #         put :drain
+    #       end
+    #       collection do
+    #         get :stats
+    #       end
+    #     end
+    #   end
+    class RouteSet
+      # @return [Array<BugBunny::Routing::Route>] Lista de rutas registradas y compiladas.
+      attr_reader :routes
+
+      # Inicializa un conjunto de rutas vacío y prepara el stack de scopes.
+      def initialize
+        @routes = []
+        @scopes = [] # Pila para rastrear el contexto (namespaces, resources, members)
+      end
+
+      # Evalúa un bloque de código en el contexto de esta instancia para construir el mapa.
+      # Utiliza `instance_eval` para exponer el DSL directamente.
+      #
+      # @yield Bloque de configuración conteniendo las definiciones de ruteo.
+      # @return [void]
+      def draw(&block)
+        instance_eval(&block)
+      end
+
+      # Borra todas las rutas registradas y limpia los scopes.
+      # Es útil para entornos de pruebas (testing) o recarga en caliente (hot-reloading).
+      #
+      # @return [void]
+      def clear!
+        @routes.clear
+        @scopes.clear
+      end
+
+      # @!group DSL de Verbos HTTP
+
+      # Registra una ruta para el verbo GET.
+      # @param path [String, Symbol] Patrón de la URL.
+      # @param to [String, nil] Destino (controlador#accion). Si es nil, se infiere del scope.
+      def get(path, to: nil);    add_route('GET', path, to: to); end
+
+      # Registra una ruta para el verbo POST.
+      # @param path [String, Symbol] Patrón de la URL.
+      # @param to [String, nil] Destino (controlador#accion). Si es nil, se infiere del scope.
+      def post(path, to: nil);   add_route('POST', path, to: to); end
+
+      # Registra una ruta para el verbo PUT.
+      # @param path [String, Symbol] Patrón de la URL.
+      # @param to [String, nil] Destino (controlador#accion). Si es nil, se infiere del scope.
+      def put(path, to: nil);    add_route('PUT', path, to: to); end
+
+      # Registra una ruta para el verbo PATCH.
+      # @param path [String, Symbol] Patrón de la URL.
+      # @param to [String, nil] Destino (controlador#accion). Si es nil, se infiere del scope.
+      def patch(path, to: nil);  add_route('PATCH', path, to: to); end
+
+      # Registra una ruta para el verbo DELETE.
+      # @param path [String, Symbol] Patrón de la URL.
+      # @param to [String, nil] Destino (controlador#accion). Si es nil, se infiere del scope.
+      def delete(path, to: nil); add_route('DELETE', path, to: to); end
+
+      # @!endgroup
+
+      # Macro que genera automáticamente las rutas CRUD para un recurso RESTful.
+      # Soporta filtrado mediante `only` y `except`, y acepta un bloque para rutas anidadas.
+      #
+      # Mapea las acciones: index (GET), show (GET /:id), create (POST),
+      # update (PUT/PATCH /:id) y destroy (DELETE /:id).
+      #
+      # @param name [Symbol, String] Nombre del recurso en plural (ej. :nodes).
+      # @param only [Array<Symbol>, Symbol, nil] Acciones a incluir exclusivamente.
+      # @param except [Array<Symbol>, Symbol, nil] Acciones a excluir.
+      # @yield Bloque para definir rutas `member` o `collection`.
+      # @return [void]
+      def resources(name, only: nil, except: nil, &block)
+        resource_path = name.to_s
+
+        # Todas las acciones estándar disponibles
+        actions = [:index, :show, :create, :update, :destroy]
+
+        # Aplicamos los filtros si existen
+        if only
+          actions &= Array(only).map(&:to_sym)
+        elsif except
+          actions -= Array(except).map(&:to_sym)
+        end
+
+        # Rutas estándar (Fuera del scope anidado)
+        get    resource_path,          to: "#{resource_path}#index"   if actions.include?(:index)
+        post   resource_path,          to: "#{resource_path}#create"  if actions.include?(:create)
+        get    "#{resource_path}/:id", to: "#{resource_path}#show"    if actions.include?(:show)
+        put    "#{resource_path}/:id", to: "#{resource_path}#update"  if actions.include?(:update)
+        patch  "#{resource_path}/:id", to: "#{resource_path}#update"  if actions.include?(:update)
+        delete "#{resource_path}/:id", to: "#{resource_path}#destroy" if actions.include?(:destroy)
+
+        # Si se pasa un bloque, abrimos un Scope de Recurso para rutas anidadas
+        if block_given?
+          with_scope({ type: :resource, name: resource_path }) do
+            instance_eval(&block)
+          end
+        end
+      end
+
+      # Define rutas aplicables a un miembro específico del recurso (Requieren un ID).
+      #
+      # Al usar este bloque, el router antepondrá automáticamente el nombre del recurso
+      # y el parámetro `:id` a la URL generada, e inferirá el controlador base.
+      #
+      # @yield Bloque conteniendo definiciones de rutas.
+      # @raise [ArgumentError] Si se llama fuera de un bloque `resources`.
+      # @return [void]
+      # @example
+      #   resources :nodes do
+      #     member do
+      #       put :drain # Genera: PUT nodes/:id/drain => NodesController#drain
+      #     end
+      #   end
+      def member(&block)
+        unless current_scope[:type] == :resource
+          raise ArgumentError, "El bloque 'member' solo puede usarse dentro de un bloque 'resources'"
+        end
+
+        with_scope({ type: :member }) do
+          instance_eval(&block)
+        end
+      end
+
+      # Define rutas aplicables a la colección completa del recurso (Sin ID).
+      #
+      # Al usar este bloque, el router antepondrá automáticamente el nombre del recurso
+      # a la URL generada e inferirá el controlador base.
+      #
+      # @yield Bloque conteniendo definiciones de rutas.
+      # @raise [ArgumentError] Si se llama fuera de un bloque `resources`.
+      # @return [void]
+      # @example
+      #   resources :nodes do
+      #     collection do
+      #       get :stats # Genera: GET nodes/stats => NodesController#stats
+      #     end
+      #   end
+      def collection(&block)
+        unless current_scope[:type] == :resource
+          raise ArgumentError, "El bloque 'collection' solo puede usarse dentro de un bloque 'resources'"
+        end
+
+        with_scope({ type: :collection }) do
+          instance_eval(&block)
+        end
+      end
+
+      # Evalúa una petición entrante contra el mapa de rutas.
+      #
+      # Recorre las rutas en el orden en que fueron definidas. La primera ruta que
+      # haga match será la ganadora. Retorna los datos necesarios para instanciar
+      # el controlador e inyectarle los parámetros dinámicos extraídos.
+      #
+      # @param method [String] Verbo HTTP entrante (ej. 'GET').
+      # @param path [String] URL entrante (ej. 'nodes/123/drain').
+      # @return [Hash, nil] Hash con `:controller`, `:action` y `:params`, o `nil` si no hay match.
+      def recognize(method, path)
+        @routes.each do |route|
+          if route.match?(method, path)
+            extracted_params = route.extract_params(path)
+
+            return {
+              controller: route.controller,
+              action: route.action,
+              params: extracted_params
+            }
+          end
+        end
+
+        # Si llegamos aquí, es un 404 seguro.
+        nil
+      end
+
+      private
+
+      # Instancia y almacena la ruta resolviendo la URL final y el controlador según el scope.
+      #
+      # @param method [String] Verbo HTTP.
+      # @param path [String, Symbol] Ruta declarada.
+      # @param to [String, nil] Destino declarado.
+      # @raise [ArgumentError] Si no se puede inferir el destino y no se provee uno.
+      # @api private
+      def add_route(method, path, to: nil)
+        final_path = path.to_s
+        final_to = to
+
+        # Inferimos rutas basadas en el Scope Activo
+        if in_scope?(:member)
+          resource = parent_resource_name
+          final_path = "#{resource}/:id/#{path}"
+          final_to ||= "#{resource}##{path}"
+        elsif in_scope?(:collection) || in_scope?(:resource)
+          resource = parent_resource_name
+          final_path = "#{resource}/#{path}"
+          final_to ||= "#{resource}##{path}"
+        end
+
+        if final_to.nil?
+          raise ArgumentError, "Falta el destino 'to:' para la ruta #{method} '#{final_path}'. Usa la sintaxis 'controlador#accion'"
+        end
+
+        @routes << Route.new(method, final_path, to: final_to)
+      end
+
+      # --- LÓGICA DE SCOPES INTERNOS ---
+
+      # Abre un nuevo contexto de alcance temporal.
+      #
+      # @param scope [Hash] Información del nuevo alcance.
+      # @yield Bloque a ejecutar dentro de este alcance.
+      # @api private
+      def with_scope(scope)
+        @scopes << scope
+        yield
+      ensure
+        @scopes.pop
+      end
+
+      # @return [Hash] El scope activo actualmente.
+      # @api private
+      def current_scope
+        @scopes.last || {}
+      end
+
+      # @param type [Symbol] El tipo de scope a verificar.
+      # @return [Boolean] Si estamos dentro de un scope del tipo especificado.
+      # @api private
+      def in_scope?(type)
+        current_scope[:type] == type
+      end
+
+      # Busca hacia atrás en la pila de scopes para encontrar el nombre del recurso padre.
+      #
+      # @return [String, nil] El nombre del recurso o nil si no se encuentra.
+      # @api private
+      def parent_resource_name
+        @scopes.reverse_each do |scope|
+          return scope[:name] if scope[:type] == :resource
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/bug_bunny/version.rb

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

data/lib/bug_bunny.rb

@@ -5,6 +5,7 @@ require 'logger'
 require_relative 'bug_bunny/version'
 require_relative 'bug_bunny/exception'
 require_relative 'bug_bunny/configuration'
+require_relative 'bug_bunny/routing/route_set'
 require_relative 'bug_bunny/middleware/base'
 require_relative 'bug_bunny/middleware/stack'
 require_relative 'bug_bunny/middleware/raise_error'
@@ -27,6 +28,13 @@ module BugBunny
 
     # @return [Bunny::Session, nil] La conexión global (Singleton) usada por procesos Rails.
     attr_accessor :global_connection
+
+    attr_writer :routes
+  end
+
+  # @return [BugBunny::Routing::RouteSet] El motor global de enrutamiento.
+  def self.routes
+    @routes ||= Routing::RouteSet.new
   end
 
   # Configura la librería BugBunny.

data/lib/generators/bug_bunny/install/templates/initializer.rb

@@ -59,3 +59,20 @@ BugBunny.configure do |config|
   # * Valor alto (10-50): Mayor throughput, pero riesgo de sobrecargar un solo worker lento.
   config.channel_prefetch = 10
 end
+
+# ==========================================
+# 🗺️ Enrutamiento Declarativo (Router)
+# ==========================================
+# Define cómo se mapean las rutas de los mensajes entrantes a tus controladores.
+# Funciona de manera similar al routes.rb de Rails.
+
+# BugBunny.routes.draw do
+#   # Macro para generar rutas CRUD estándar (index, show, create, update, destroy)
+#   resources :services
+#
+#   # Rutas estáticas o custom
+#   get 'health_checks/up', to: 'health_checks#up'
+#
+#   # Rutas con parámetros dinámicos (:id, :cluster_id, etc.)
+#   put 'nodes/:id/drain', to: 'nodes#drain'
+# end

data/test/test_helper.rb

@@ -107,3 +107,14 @@ module IntegrationHelper
     worker_thread&.kill
   end
 end
+
+# test/test_helper.rb (Al final del archivo)
+
+BugBunny.routes.draw do
+  # Rutas necesarias para infrastructure_test.rb
+  resources :ping
+
+  # Rutas necesarias para manual_client_test.rb
+  get 'echo', to: 'echo#index'
+  post 'test', to: 'test#index' # o el controlador que maneje 'test'
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bug_bunny
 version: !ruby/object:Gem::Version
-  version: 3.1.6
+  version: 4.0.0
 platform: ruby
 authors:
 - gabix
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-02-27 00:00:00.000000000 Z
+date: 2026-03-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bunny
@@ -247,6 +247,8 @@ files:
 - lib/bug_bunny/railtie.rb
 - lib/bug_bunny/request.rb
 - lib/bug_bunny/resource.rb
+- lib/bug_bunny/routing/route.rb
+- lib/bug_bunny/routing/route_set.rb
 - lib/bug_bunny/session.rb
 - lib/bug_bunny/version.rb
 - lib/generators/bug_bunny/install/install_generator.rb