bug_bunny 4.5.3 → 4.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9432574fbe3a1b19c3f9eb4317cc66a10fc1e0f5b536f13d4fffdba1aa086a3d
-  data.tar.gz: 779dd27c82ef03139dea34dc6969ef66385793377214149a8f34d416f46e5b79
+  metadata.gz: 9c9f75619decb8d892d2bfe8c56424822672b6b6b5f3be85442be1399c38e76a
+  data.tar.gz: 7fc1e66a10f46d0a6120dd6164b10b0f1b30d2ff91e8d5daed4358f771f2cc49
 SHA512:
-  metadata.gz: 20091c38f5f4b049aa4273e58f6b067a4502a388681048041ac35b341f88331412d36f2d3d3cf4baae218bb0a6a53759629761d9d50d2ca4b3ee048254f5de46
-  data.tar.gz: df4c691e043949d459f52d77e899f7a91fdad7ba2e9122068f46e973ba3cc670d50b17019167318a1290f73b7b8f9cff28dbd30773a18cb933d8de39f6dac34d
+  metadata.gz: fd5f4141f5a7892f84d5b3894535632fe63ce24320637a5896530b025c4f3dc8f002f75c41f7cbec57258bca857d58cd1d531c0abf3d6f2047e049cc6119ae98
+  data.tar.gz: c13414d24ee769acb483fe4a9ee1f9aa2073ea6bf8bea81e1ac290499ad45cd85471ffd022a304bb6da9cc56e737f868bc441870a1b084b05a60892c6f3b6366

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [4.6.0] - 2026-03-31
+
+### ✨ New Features
+* **Consumer Middleware Stack:** Se introdujo `BugBunny::ConsumerMiddleware::Stack`, un pipeline de middlewares que se ejecuta antes de que la gema procese cada mensaje AMQP (antes del primer log `consumer.message_received`). Es el punto de extensión oficial para tracing distribuido, autenticación y auditoría a nivel de consumer.
+    * Clase base `BugBunny::ConsumerMiddleware::Base` con interfaz `call(delivery_info, properties, body)`.
+    * Acceso directo via `BugBunny.consumer_middlewares.use MyMiddleware`.
+    * Soporte de **auto-registro transparente**: gemas externas como `exis_ray` pueden registrarse al ser requeridas sin que el usuario toque el bloque `configure`.
+    * Orden de ejecución FIFO. Sin middlewares registrados, el overhead es cero.
+* **RPC Trace Propagation (bidireccional):** BugBunny ahora propaga trace context en ambas direcciones del ciclo RPC:
+    * `config.rpc_reply_headers` (Proc) — callback invocado en el consumer justo antes del `basic_publish` del reply. Retorna headers AMQP a inyectar en la respuesta (ej: `X-Amzn-Trace-Id` actualizado con el span del consumer).
+    * `config.on_rpc_reply` (Proc) — callback invocado en el thread llamante del publisher tras recibir el reply, con los headers AMQP de la respuesta. Permite hidratar trace context en el publisher sin exponer los headers en la interfaz pública del método `rpc`.
+    * Ejemplo consumer: `config.rpc_reply_headers = -> { { 'X-Amzn-Trace-Id' => ExisRay::Tracer.generate_trace_header } }`
+    * Ejemplo publisher: `config.on_rpc_reply = ->(headers) { ExisRay::Tracer.hydrate(headers['X-Amzn-Trace-Id']) }` Retorna un Hash de headers AMQP que se inyectan en la respuesta, permitiendo propagar trace context generado por el consumer (ej: `X-Amzn-Trace-Id` actualizado). Cero overhead cuando no está configurado.
+    * Ejemplo: `config.rpc_reply_headers = -> { { 'X-Amzn-Trace-Id' => ExisRay::Tracer.generate_trace_header } }`
+* **Observability — Hash quoting:** `safe_log` ahora aplica la misma regla de quoting a valores `Hash` que a `String`: si el JSON contiene espacios, se inspecciona; si no, se emite sin comillas, facilitando el parseo automático en motores de logs.
+
 ## [4.5.3] - 2026-03-30
 
 ### 🐛 Bug Fixes

data/README.md

@@ -206,6 +206,59 @@ end
 
 ---
 
+## 🔗 Consumer Middleware Stack
+
+BugBunny expone un middleware stack que se ejecuta **antes** de que la gema procese cada mensaje entrante (antes del primer log `consumer.message_received`). Es el punto ideal para hidratar contexto de tracing distribuido, autenticación, auditoría, etc.
+
+### Implementar un middleware
+
+```ruby
+class MyMiddleware < BugBunny::ConsumerMiddleware::Base
+  def call(delivery_info, properties, body)
+    # lógica pre-procesamiento
+    # properties.headers contiene todos los headers AMQP custom
+    @app.call(delivery_info, properties, body)
+    # lógica post-procesamiento (opcional)
+  end
+end
+```
+
+### Registrar un middleware
+
+```ruby
+BugBunny.configure do |config|
+  # ...
+end
+
+BugBunny.consumer_middlewares.use MyMiddleware
+```
+
+### Auto-registro desde una gema externa
+
+Las gemas de integración pueden registrarse automáticamente al ser requeridas, sin que el usuario tenga que tocar el bloque `configure`:
+
+```ruby
+# lib/exis_ray/bug_bunny/consumer_tracing.rb
+require 'exis_ray/bug_bunny/consumer_tracing_middleware'
+BugBunny.consumer_middlewares.use ExisRay::BugBunny::ConsumerTracingMiddleware
+
+# El usuario solo necesita:
+# require 'exis_ray/bug_bunny/consumer_tracing'
+```
+
+### Datos disponibles en el middleware
+
+| Argumento | Tipo | Contenido |
+|---|---|---|
+| `delivery_info` | `Bunny::DeliveryInfo` | `routing_key`, `exchange`, `delivery_tag` |
+| `properties` | `Bunny::MessageProperties` | `headers` (headers AMQP custom), `correlation_id`, `reply_to`, `content_type` |
+| `body` | `String` | Payload crudo del mensaje |
+
+> **Orden de ejecución:** FIFO — el primero en registrarse es el primero en ejecutarse.
+> `Middleware A → Middleware B → process_message`
+
+---
+
 ## 🔎 Observabilidad y Tracing
 
 BugBunny implementa Distributed Tracing nativo y sigue los estándares de observabilidad de **ExisRay** para logs estructurados.

data/lib/bug_bunny/configuration.rb

@@ -96,6 +96,23 @@ module BugBunny
     #   @example { durable: true, exclusive: false }
     attr_accessor :queue_options
 
+    # @return [BugBunny::ConsumerMiddleware::Stack] Stack de middlewares ejecutados antes de procesar cada mensaje.
+    #   Los middlewares se registran con {BugBunny::ConsumerMiddleware::Stack#use}.
+    attr_reader :consumer_middlewares
+
+    # @return [Proc, nil] Callback invocado justo antes del `basic_publish` del reply RPC.
+    #   Debe retornar un Hash de headers AMQP a inyectar en la respuesta.
+    #   Ideal para propagar trace context (ej: X-Amzn-Trace-Id) generado por el consumer.
+    #   @example
+    #     config.rpc_reply_headers = -> { { 'X-Amzn-Trace-Id' => ExisRay::Tracer.generate_trace_header } }
+    attr_accessor :rpc_reply_headers
+
+    # @return [Proc, nil] Callback invocado en el thread llamante tras recibir el reply RPC,
+    #   con los headers AMQP de la respuesta. Permite hidratar trace context en el publisher.
+    #   @example
+    #     config.on_rpc_reply = ->(headers) { ExisRay::Tracer.hydrate(headers['X-Amzn-Trace-Id']) }
+    attr_accessor :on_rpc_reply
+
     # @!endgroup
 
     # Inicializa la configuración con valores por defecto seguros.
@@ -135,6 +152,10 @@ module BugBunny
       # Inicialización de opciones de infraestructura como hashes vacíos para permitir fusiones posteriores.
       @exchange_options = {}
       @queue_options = {}
+
+      @consumer_middlewares = ConsumerMiddleware::Stack.new
+      @rpc_reply_headers = nil
+      @on_rpc_reply = nil
     end
 
     # Construye la URL de conexión AMQP basada en los atributos configurados.

data/lib/bug_bunny/consumer.rb

@@ -87,16 +87,19 @@ module BugBunny
 
         q.subscribe(manual_ack: true, block: block) do |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
+          core = -> {
+            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
+          }
+
+          BugBunny.configuration.consumer_middlewares.call(delivery_info, properties, body, &core)
         end
       rescue StandardError => e
         attempt += 1
@@ -241,11 +244,13 @@ module BugBunny
     # @return [void]
     def reply(payload, reply_to, correlation_id)
       safe_log(:debug, "consumer.rpc_reply", reply_to: reply_to, correlation_id: correlation_id)
+      extra_headers = BugBunny.configuration.rpc_reply_headers&.call || {}
       session.channel.default_exchange.publish(
         payload.to_json,
         routing_key: reply_to,
         correlation_id: correlation_id,
-        content_type: 'application/json'
+        content_type: 'application/json',
+        headers: extra_headers
       )
     end
 

data/lib/bug_bunny/consumer_middleware.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module BugBunny
+  # Infraestructura de middleware para el Consumer AMQP.
+  #
+  # Permite inyectar lógica transversal (tracing, autenticación, logging) en el
+  # pipeline de procesamiento de mensajes, antes de que la gema procese el mensaje.
+  #
+  # Cada middleware recibe `(delivery_info, properties, body)` y debe llamar a
+  # `@app.call(delivery_info, properties, body)` para continuar la cadena.
+  #
+  # @example Registrar un middleware desde una gema externa (auto-registro al hacer require)
+  #   BugBunny.consumer_middlewares.use MyTracing::ConsumerMiddleware
+  #
+  # @example Implementar un middleware propio
+  #   class MyMiddleware < BugBunny::ConsumerMiddleware::Base
+  #     def call(delivery_info, properties, body)
+  #       # lógica pre-procesamiento (ej: hidratar contexto de tracing)
+  #       @app.call(delivery_info, properties, body)
+  #       # lógica post-procesamiento
+  #     end
+  #   end
+  module ConsumerMiddleware
+    # Clase base para middlewares del Consumer.
+    #
+    # @abstract Subclasificá e implementá {#call}.
+    class Base
+      # @param app [#call] El siguiente eslabón en la cadena (otro middleware o el core).
+      def initialize(app)
+        @app = app
+      end
+
+      # Procesa el mensaje y delega al siguiente eslabón.
+      #
+      # @param delivery_info [Bunny::DeliveryInfo] Metadatos de entrega AMQP.
+      # @param properties [Bunny::MessageProperties] Headers y propiedades AMQP.
+      # @param body [String] Payload crudo del mensaje.
+      # @return [void]
+      def call(delivery_info, properties, body)
+        @app.call(delivery_info, properties, body)
+      end
+    end
+
+    # Gestiona y ejecuta la cadena de middlewares del Consumer.
+    class Stack
+      def initialize
+        @middlewares = []
+      end
+
+      # Registra un middleware en la cadena.
+      #
+      # @param middleware_class [Class] Clase que hereda de {Base}.
+      # @return [self]
+      def use(middleware_class)
+        @middlewares << middleware_class
+        self
+      end
+
+      # @return [Boolean] `true` si no hay middlewares registrados.
+      def empty?
+        @middlewares.empty?
+      end
+
+      # Ejecuta la cadena de middlewares envolviendo el bloque core.
+      #
+      # @param delivery_info [Bunny::DeliveryInfo]
+      # @param properties [Bunny::MessageProperties]
+      # @param body [String]
+      # @yieldreturn [void] El bloque core a ejecutar al final de la cadena.
+      # @return [void]
+      def call(delivery_info, properties, body, &core)
+        terminal = ->(_di, _props, _body) { core.call }
+
+        chain = @middlewares.reverse.inject(terminal) do |next_step, middleware_class|
+          middleware_class.new(next_step)
+        end
+
+        chain.call(delivery_info, properties, body)
+      end
+    end
+  end
+end

data/lib/bug_bunny/observability.rb

@@ -23,7 +23,9 @@ module BugBunny
 
         formatted = case val
                     when Numeric then val
-                    when Hash    then val.to_json # Genera JSON compacto analizable
+                    when Hash
+                      json = val.to_json
+                      json.include?(" ") ? json.inspect : json
                     when String  then val.include?(" ") ? val.inspect : val
                     else val.to_s.include?(" ") ? val.to_s.inspect : val
                     end

data/lib/bug_bunny/producer.rb

@@ -82,13 +82,17 @@ module BugBunny
         safe_log(:debug, "producer.rpc_waiting", correlation_id: cid, timeout_s: wait_timeout)
 
         # Bloqueamos el hilo aquí hasta que llegue la respuesta o expire el timeout
-        response_payload = future.value(wait_timeout)
+        result = future.value(wait_timeout)
 
-        if response_payload.nil?
+        if result.nil?
           raise BugBunny::RequestTimeout, "Timeout waiting for RPC: #{request.path} [#{request.method}]"
         end
 
-        parse_response(response_payload)
+        BugBunny.configuration.on_rpc_reply&.call(result[:headers])
+
+        safe_log(:debug, "producer.rpc_response_received", correlation_id: cid)
+
+        parse_response(result[:body])
       ensure
         # Limpieza vital para evitar fugas de memoria en el mapa
         @pending_requests.delete(cid)
@@ -153,9 +157,8 @@ module BugBunny
         # Consumimos sin ack (auto-ack) porque reply-to no soporta acks manuales de forma estándar
         @session.channel.basic_consume('amq.rabbitmq.reply-to', '', true, false, nil) do |_, props, body|
           cid = props.correlation_id.to_s
-          safe_log(:debug, "producer.rpc_response_received", correlation_id: cid)
           if (future = @pending_requests[cid])
-            future.set(body)
+            future.set({ body: body, headers: props.headers || {} })
           else
             safe_log(:warn, "producer.rpc_response_orphaned", correlation_id: cid)
           end

data/lib/bug_bunny/version.rb

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

data/lib/bug_bunny.rb

@@ -9,6 +9,7 @@ require_relative 'bug_bunny/observability'
 require_relative 'bug_bunny/routing/route_set'
 require_relative 'bug_bunny/middleware/base'
 require_relative 'bug_bunny/middleware/stack'
+require_relative 'bug_bunny/consumer_middleware'
 require_relative 'bug_bunny/middleware/raise_error'
 require_relative 'bug_bunny/middleware/json_response'
 require_relative 'bug_bunny/client'
@@ -41,6 +42,12 @@ module BugBunny
     @routes ||= Routing::RouteSet.new
   end
 
+  # @return [BugBunny::ConsumerMiddleware::Stack] Stack global de middlewares del Consumer.
+  # Atajo para `BugBunny.configuration.consumer_middlewares`.
+  def self.consumer_middlewares
+    configuration.consumer_middlewares
+  end
+
   # Configura la librería BugBunny.
   # Si no se ha configurado previamente, inicializa una nueva configuración por defecto.
   #

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bug_bunny
 version: !ruby/object:Gem::Version
-  version: 4.5.3
+  version: 4.6.0
 platform: ruby
 authors:
 - gabix
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-03-30 00:00:00.000000000 Z
+date: 2026-03-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bunny
@@ -237,6 +237,7 @@ files:
 - lib/bug_bunny/client.rb
 - lib/bug_bunny/configuration.rb
 - lib/bug_bunny/consumer.rb
+- lib/bug_bunny/consumer_middleware.rb
 - lib/bug_bunny/controller.rb
 - lib/bug_bunny/exception.rb
 - lib/bug_bunny/middleware/base.rb