bug_bunny 3.0.6 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0a8a31414070c751adbf073b7588e31d866ed7f1047abfbadad6de2ae75e411e
-  data.tar.gz: 438a1f9d2a2d3cd6f012f16a5c1349c42f20c87be1cb76212a841c528004bdfd
+  metadata.gz: 3b31963a71fce5b70886e19ee276f174d55052ffce7fdcd90b4b662e70ac6080
+  data.tar.gz: 851e107eec43ebe45ec3059d2148197e756299fdcf7a5efb5120e0856a2ca3b8
 SHA512:
-  metadata.gz: 130ae01d89317ad8ecf2c9bb832d4ce235f6eb23df903e256ea47a5669bc2b300239b41beabcbb6a2e8dc44a674ac3eaa90cb8fab0bc44037c377e1503317022
-  data.tar.gz: 603106d7e627b086624d88914601b6cdeb465162116cb6821ca519b5a75c20b7700a0a7ee578e44ef3b311784f69bc17efea1e73a7d32403e5c19efb6b21836a
+  metadata.gz: 849447e5f3655f10f3bff047db0dc3ce5bbc2d6190a8db030ffe7b7a1d9619eebb9ac907c30f87e059d5e1c0b1dfce81f80b8f1768346f1fcee7b62f678b0243
+  data.tar.gz: bacfee7008aae385333d3b4e9139b0eeb89cdb1332259f19ec34491db71a1cb824004b968f54a699b7b0e35b94eca5ff4c134bb5ff04a7ffa095ab9d533408e3

data/CHANGELOG.md

@@ -1,4 +1,21 @@
 # Changelog
+## [3.1.0] - 2026-02-18
+
+### 🌟 New Features: Observability & Tracing
+* **Distributed Tracing Stack:** Implemented a native distributed tracing system that ensures full visibility from the Producer to the Consumer/Worker.
+    * **Producer:** Messages now automatically carry a `correlation_id`. Added support for custom Middlewares to inject IDs from the application context (e.g., Rails `Current.request_id` or Sidekiq IDs).
+    * **Consumer:** Automatically extracts the `correlation_id` from AMQP headers and wraps the entire execution in a **Tagged Logger** block (e.g., `[d41d8cd9...] [API] Processing...`).
+    * **Controller:** Introduced `self.log_tags` to allow injecting rich business context into logs (e.g., `[Tenant-123]`) using the native `around_action` hook.
+
+### 🛡 Security
+* **Router Hardening:** Added a strict inheritance check in the `Consumer`.
+    * **Prevention:** The router now verifies that the instantiated class inherits from `BugBunny::Controller` before execution.
+    * **Impact:** Prevents potential **Remote Code Execution (RCE)** vulnerabilities where an attacker could try to instantiate arbitrary system classes (like `::Kernel`) via the `type` header.
+
+### 🐛 Bug Fixes
+* **RPC Type Consistency:** Fixed a critical issue where RPC responses were ignored if the `correlation_id` was an Integer.
+    * **Fix:** The Producer now strictly normalizes all correlation IDs to Strings (`.to_s`) during both storage (pending requests) and retrieval (reply listener), ensuring reliable matching regardless of the ID format.
+
 ## [3.0.6] - 2026-02-17
 
 ### ♻️ Refactor & Standards

data/README.md

@@ -54,12 +54,24 @@ BugBunny.configure do |config|
 
   # --- Logging (Niveles recomendados) ---
   # Logger de BugBunny: Muestra tus requests (INFO)
-  config.logger = Logger.new(STDOUT)
-  config.logger.level = Logger::INFO
+  rails_logger = Rails.logger
+
+  if defined?(ActiveSupport::TaggedLogging) && !rails_logger.respond_to?(:tagged)
+    config.logger = ActiveSupport::TaggedLogging.new(rails_logger)
+  else
+    config.logger = rails_logger
+  end
 
   # Logger de Bunny (Driver): Silencia el ruido de bajo nivel (WARN)
-  config.bunny_logger = Logger.new(STDOUT)
+  if defined?(ActiveSupport::TaggedLogging) && !rails_logger.respond_to?(:tagged)
+    config.bunny_logger = ActiveSupport::TaggedLogging.new(rails_logger)
+  else
+    config.bunny_logger = rails_logger
+  end
   config.bunny_logger.level = Logger::WARN
+
+  # Controller Namaspeace
+  config.controller_namespace = 'MyApp::AsyncHandlers' # Default: 'Rabbit::Controllers'
 end
 ```
 
@@ -149,6 +161,80 @@ svc.save
 # Log: [BugBunny] [POST] '/services' | Routing Key: 'urgent'
 ```
 
+### Soporte de Parámetros Anidados (Nested Queries)
+En la versión 3.0.3 arreglaste la serialización usando `Rack::Utils`. Esto es una "feature" poderosa que permite filtrar por hashes complejos, algo muy común en APIs modernas.
+
+**Sugerencia:** Agregar un ejemplo en la sección **CRUD RESTful > LEER (GET)**:
+
+```ruby
+# --- LEER CON FILTROS AVANZADOS ---
+# Soporta hashes anidados (gracias a Rack::Utils)
+# Envia: GET services?q[status]=active&q[tags][]=web
+Manager::Service.where(q: { status: 'active', tags: ['web'] })
+```
+
+### 🔌 Manipulación de Headers (Middleware)
+
+BugBunny permite interceptar y modificar las peticiones antes de que se envíen a RabbitMQ utilizando `client_middleware`. Esto es ideal para inyectar trazas, autenticación o metadatos de contexto.
+
+Existen 3 formas principales de usarlo:
+
+#### 1. Definición Inline (Rápida)
+Ideal para inyectar headers estáticos específicos de un recurso.
+```ruby
+class Payment < BugBunny::Resource
+  client_middleware do |stack|
+    stack.use(Class.new(BugBunny::Middleware::Base) do
+      def on_request(env)
+        env.headers['X-Service-Version'] = 'v2'
+        env.headers['Content-Type'] = 'application/json'
+      end
+    end)
+  end
+end
+```
+
+#### 2. Clase Reutilizable (Recomendada)
+Si tienes lógica compartida (ej: Autenticación), define una clase y úsala en múltiples recursos.
+
+```ruby
+# app/middleware/auth_middleware.rb
+class AuthMiddleware < BugBunny::Middleware::Base
+  def on_request(env)
+    env.headers['Authorization'] = "Bearer #{ENV['API_KEY']}"
+  end
+end
+
+# app/models/user.rb
+class User < BugBunny::Resource
+  client_middleware do |stack|
+    stack.use AuthMiddleware
+  end
+end
+```
+
+#### 3. Contexto Dinámico (Pro)
+Permite inyectar valores que cambian en cada petición (como el Usuario actual o Tenant), leyendo de variables globales thread-safe (como CurrentAttributes en Rails).
+
+```ruby
+# Middleware que lee el Tenant actual
+# app/middleware/tenant_middleware.rb
+class TenantMiddleware < BugBunny::Middleware::Base
+  def on_request(env)
+    # Ejemplo usando Rails CurrentAttributes
+    if Current.tenant_id
+      env.headers['X-Tenant-ID'] = Current.tenant_id
+    end
+  end
+end
+
+class Order < BugBunny::Resource
+  client_middleware do |stack|
+    stack.use TenantMiddleware
+  end
+end
+```
+
 ---
 
 ## 📡 Modo Servidor (Worker & Router)
@@ -217,7 +303,21 @@ class ApplicationController < BugBunny::Controller
 end
 ```
 
-### 3. Tabla de Ruteo (Convención)
+### 3. Namespace de Controladores (Opcional)
+
+Por defecto, BugBunny busca los controladores dentro del módulo `Rabbit::Controllers`. Esto implica que tus archivos deben estar en `app/rabbit/controllers/`.
+
+Si prefieres organizar tus consumidores en otro lugar (ej: dentro de un dominio específico o carpeta existente), puedes cambiar el namespace.
+
+**Configuración:**
+```ruby
+# config/initializers/bug_bunny.rb
+BugBunny.configure do |config|
+  config.controller_namespace = 'Billing::Events'
+end
+```
+
+### 4. Tabla de Ruteo (Convención)
 
 El Router infiere la acción automáticamente:
 
@@ -230,6 +330,116 @@ El Router infiere la acción automáticamente:
 | `DELETE` | `services/12` | `ServicesController` | `destroy` |
 | `POST` | `services/12/restart` | `ServicesController` | `restart` (Custom) |
 
+### 🔎 Observabilidad y Logging
+
+BugBunny implementa un sistema de **Tracing Distribuido** nativo. Esto permite rastrear una petición desde que se origina en tu aplicación (Producer) hasta que es procesada por el worker (Consumer), manteniendo el mismo ID de traza (`correlation_id`) en todos los logs.
+
+#### 1. Productor: Inyectar el Trace ID
+
+Para asegurar que los mensajes salgan de tu aplicación con el ID de traza correcto (por ejemplo, el `X-Request-Id` de Rails, Sidekiq o tu propio `Current.request_id`), debes inyectarlo antes de publicar el mensaje.
+
+La forma recomendada es crear un Middleware y registrarlo globalmente.
+
+**A. Crear el Middleware**
+
+```ruby
+# app/middleware/correlation_injector.rb
+class CorrelationInjector < BugBunny::Middleware::Base
+  def on_request(env)
+    # Ejemplo: Si usas Rails CurrentAttributes o similar
+    if defined?(Current) && Current.request_id
+      env.correlation_id = Current.request_id
+    end
+  end
+end
+```
+
+**B. Registrar el Middleware (Initializer)**
+
+```ruby
+# config/initializers/bug_bunny.rb
+require 'bug_bunny'
+require_relative '../../app/middleware/correlation_injector'
+
+# Módulo para interceptar la inicialización de cualquier cliente
+module BugBunnyGlobalMiddleware
+  def initialize(pool:)
+    super
+    @stack.use CorrelationInjector
+  end
+end
+
+# Aplicamos el parche para que afecte a Resources y Clientes manuales
+BugBunny::Client.prepend(BugBunnyGlobalMiddleware)
+```
+
+---
+
+#### 2. Consumidor: Logging Automático
+
+El consumidor de BugBunny está diseñado para garantizar la trazabilidad "out-of-the-box".
+
+##### A. Comportamiento por Defecto
+Al recibir un mensaje, el Consumidor realiza automáticamente los siguientes pasos:
+1. Extrae el `correlation_id` de las propiedades AMQP (o genera un UUID si no existe).
+2. Envuelve todo el procesamiento en un bloque de log etiquetado (`tagged logging`).
+3. Pasa el ID al Controlador.
+
+**No necesitas configurar nada.** Tus logs se verán así automáticamente:
+
+```text
+[d41d8cd9-8f00...] [Consumer] Listening on queue...
+[d41d8cd9-8f00...] [API] Procesando usuario 123...
+```
+
+##### B. Configuración Global (Initializer)
+Si deseas agregar tags estáticos que aparezcan en **todos** los mensajes procesados por este worker (como el nombre del servicio, versión o entorno), agrégalos a `config.log_tags`.
+
+> **Nota:** No agregues `:uuid` aquí, ya que el Consumidor lo agrega automáticamente.
+
+```ruby
+BugBunny.configure do |config|
+  # ... configuración de conexión ...
+
+  # Tags globales adicionales
+  config.log_tags = [
+    'WORKER',
+    ->(_) { ENV['APP_VERSION'] }
+  ]
+end
+```
+
+**Resultado en Log:**
+```text
+[d41d8cd9...] [WORKER] [v1.0.2] [API] Procesando mensaje...
+```
+
+##### C. Configuración por Controlador (Contexto Rico)
+Para agregar información específica del mensaje o lógica de negocio (como IDs de inquilinos, usuario actual, o headers específicos), utiliza `self.log_tags` en tus controladores.
+
+Esto aprovecha el `around_action` nativo de la gema para inyectar contexto.
+
+```ruby
+# app/rabbit/controllers/application_controller.rb
+module Rabbit
+  module Controllers
+    class ApplicationController < BugBunny::Controller
+      # Define tags dinámicos basados en el mensaje actual
+      self.log_tags = [
+        ->(c) { c.params[:tenant_id] },      # Tag del Tenant (si viene en el body)
+        ->(c) { c.headers['X-Source'] }      # Tag del origen
+      ]
+    end
+  end
+end
+```
+
+**Resultado Final en Log:**
+(UUID Automático + Tag Global + Tag de Controlador)
+```text
+[d41d8cd9...] [WORKER] [Tenant-55] [Console] Creando usuario...
+```
+
 ---
 
 ## 🔌 Modo Publisher (Cliente Manual)
@@ -256,6 +466,20 @@ client.publish('audit/events',
 )
 ```
 
+### ⚠️ Consideraciones sobre RPC (Direct Reply-To)
+
+BugBunny utiliza el mecanismo nativo `amq.rabbitmq.reply-to` para las peticiones RPC. Esto maximiza el rendimiento eliminando la necesidad de crear colas temporales por cada petición.
+
+**Trade-off:**
+Al usar este mecanismo, las respuestas son efímeras. Si el proceso Cliente (tu aplicación Rails/Sidekiq) se reinicia abruptamente justo después de enviar la petición pero milisegundos antes de procesar la respuesta, **esa respuesta se perderá**.
+
+**Recomendación:**
+Diseña tus acciones de Controlador RPC (`POST`, `PUT`) para que sean **idempotentes**.
+* *Mal diseño:* "Crear pago" (si se reintenta, cobra doble).
+* *Buen diseño:* "Crear pago con ID X" (si se reintenta y ya existe, devuelve el recibo existente).
+
+Esto permite que, ante un `BugBunny::RequestTimeout` por caída del cliente, puedas reintentar la operación de forma segura.
+
 ---
 
 ## 🏗 Arquitectura REST-over-AMQP

data/Rakefile

@@ -1,8 +1,12 @@
-# frozen_string_literal: true
+require 'bundler/gem_tasks'
+require 'rake/testtask'
 
-require "bundler/gem_tasks"
-require "rubocop/rake_task"
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/*_test.rb']
+  t.verbose = true
+  t.warning = false
+end
 
-RuboCop::RakeTask.new
-
-task default: :rubocop
+task default: :test

data/lib/bug_bunny/configuration.rb

@@ -57,10 +57,16 @@ module BugBunny
     # @return [Integer] Intervalo en segundos para verificar la salud de la cola.
     attr_accessor :health_check_interval
 
+    # @return [String] Namespace base donde se buscarán los controladores (default: 'Rabbit::Controllers').
+    attr_accessor :controller_namespace
+
+    # @return [Array<Symbol, Proc, String>]
+    attr_accessor :log_tags
+
     # Inicializa la configuración con valores por defecto seguros.
     def initialize
-      @host = '127.0.0.1' # Valor por defecto explícito
-      @port = 5672        # <--- AGREGADO (Default RabbitMQ Port)
+      @host = '127.0.0.1'
+      @port = 5672
       @username = 'guest'
       @password = 'guest'
       @vhost = '/'
@@ -80,6 +86,11 @@ module BugBunny
       @channel_prefetch = 1
       @rpc_timeout = 10
       @health_check_interval = 60
+
+      # Configuración por defecto para mantener compatibilidad
+      @controller_namespace = 'Rabbit::Controllers'
+
+      @log_tags = [:uuid]
     end
 
     # Construye la URL de conexión AMQP basada en los atributos configurados.

data/lib/bug_bunny/consumer.rb

@@ -65,7 +65,17 @@ module BugBunny
       start_health_check(queue_name)
 
       q.subscribe(manual_ack: true, block: block) do |delivery_info, properties, body|
-        process_message(delivery_info, properties, body)
+        trace_id = properties.correlation_id
+
+        logger = BugBunny.configuration.logger
+
+        if logger.respond_to?(:tagged)
+          logger.tagged(trace_id) { process_message(delivery_info, properties, body) }
+        elsif defined?(Rails) && Rails.logger.respond_to?(:tagged)
+          Rails.logger.tagged(trace_id) { process_message(delivery_info, properties, body) }
+        else
+          process_message(delivery_info, properties, body)
+        end
       end
     rescue StandardError => e
       BugBunny.configuration.logger.error("[Consumer] Connection Error: #{e.message}. Retrying...")
@@ -84,20 +94,28 @@ module BugBunny
     # @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' header. Message rejected.")
+      BugBunny.configuration.logger.debug("delivery_info: #{delivery_info}, properties: #{properties}, body: #{body}")
+      # 1. Recuperación Robusta del Path (Ruta)
+      path = properties.type
+      if path.nil? || path.empty?
+        path = properties.headers ? properties.headers['path'] : nil
+      end
+
+      if path.nil? || path.empty?
+        BugBunny.configuration.logger.error("[Consumer] Missing 'type' or 'path' 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'
+      # 2. Recuperación Robusta del Verbo HTTP
+      headers_hash = properties.headers || {}
+      http_method = headers_hash['x-http-method'] || headers_hash['method'] || 'GET'
 
-      # 2. Router: Inferencia de Controlador y Acción
-      route_info = router_dispatch(http_method, properties.type)
+      # 3. Router: Inferencia de Controlador y Acción
+      route_info = router_dispatch(http_method, path)
 
-      headers = {
-        type: properties.type,
+      request_metadata = {
+        type: path,
         http_method: http_method,
         controller: route_info[:controller],
         action: route_info[:action],
@@ -106,32 +124,41 @@ module BugBunny
         content_type: properties.content_type,
         correlation_id: properties.correlation_id,
         reply_to: properties.reply_to
-      }
+      }.merge(properties.headers)
+
+      # 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
 
-      # 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
+        # Construcción: "Messaging::Handlers" + "::" + "Users"
+        controller_class_name = "#{namespace}::#{controller_name}"
 
-      # 4. Ejecución del Pipeline (Filtros -> Acción)
-      response_payload = controller_class.call(headers: headers, body: body)
+        controller_class = controller_class_name.constantize
 
-      # 5. Respuesta RPC (Si se solicita respuesta)
+        unless controller_class < BugBunny::Controller
+          raise BugBunny::SecurityError, "Class #{controller_class} is not a valid BugBunny Controller"
+        end
+      rescue NameError => _e
+        BugBunny.configuration.logger.error("[Consumer] Controller not found: #{controller_class_name}")
+        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)
+      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
 
-      # 6. Acknowledge (Confirmación de procesado)
+      # 7. Acknowledge
       session.channel.ack(delivery_info.delivery_tag)
 
-    rescue NameError => e
-      # 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)
@@ -189,6 +216,7 @@ module BugBunny
     # @param correlation_id [String] ID para correlacionar la respuesta con la petición original.
     # @return [void]
     def reply(payload, reply_to, correlation_id)
+      BugBunny.configuration.logger.debug("[Consumer] 📤 Enviando REPLY a: #{reply_to} | ID: #{correlation_id}")
       session.channel.default_exchange.publish(
         payload.to_json,
         routing_key: reply_to,