bug_bunny 3.1.1 → 3.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fc4ecbe75edaf8811acfe2929b74fb4aa98cb65c61d74aca4f5a1320b40a94b8
-  data.tar.gz: c3ed5b1e5a773ab8d80fbecc1b96d4a04a62dd1f0b1b5414a2275f497fcde9ee
+  metadata.gz: 4aab7949b09bfbf861d4a9ff736bc3bef832fdb3c8a302924544783bdbc9e1bf
+  data.tar.gz: 12b73641a812ec4ce72d2a5ad8992a1f2b91c4b0b11ce181aac02fe3a4912751
 SHA512:
-  metadata.gz: ee79317a849f3b62e25791f8c3e2bc73e55e6531c697f04ef7896ff438bfac817c5efef15f170769fc3c441a212776f6cec90d0a02b7a52764208512862df1af
-  data.tar.gz: a4e7c0a8a5661e285978376b12c13977fcb9c522a4a19b8c15177d81917084dde7b595baa30c8ef142547d2e35a5983abec7ccaf2a8b6a52e044e51b8196889f
+  metadata.gz: 2f4475f1754c1de91be6576d4fabb23d025b1f3735d4d76d3123415e71b907d2bfc307dd8e8f4a921ad5a11b2524cd85a1ee17ea3fb1d42f6e15c62ddef01425
+  data.tar.gz: c3973288d2d394121491ffb3c7fa809b8841c9fdc3fc87486fb807b62b6f948e48298fd9f4b696132c9b86d448dad82bd4cfa909c39384efc2ab1b7729c15f31

data/CHANGELOG.md

@@ -1,4 +1,29 @@
 # Changelog
+## [3.1.3] - 2026-02-19
+
+### 🏗️ Architectural Refactoring (Middleware Standardization)
+* **Centralized Error Handling:** Refactored `BugBunny::Resource` to completely delegate HTTP status evaluation to the `RaiseError` middleware. The ORM now operates strictly on a "Happy Path" mentality, rescuing semantic exceptions (`NotFound`, `UnprocessableEntity`) natively.
+* **Middleware Injection Enforcement:** `BugBunny::Resource` now explicitly guarantees that `BugBunny::Middleware::RaiseError` and `BugBunny::Middleware::JsonResponse` are the core of the stack, ensuring consistent data parsing and error raising before any custom user middlewares are executed.
+
+### ✨ New Features & Improvements
+* **Smart Validation Errors:** `BugBunny::UnprocessableEntity` (422) is now intelligent. It automatically parses the remote worker's response payload, gracefully handling string fallbacks or extracting the standard Rails `{ errors: ... }` convention to accurately populate local object validations.
+* **HTTP 409 Conflict Support:** Added native support for `409 Conflict` mapping it to the new `BugBunny::Conflict` exception. Ideal for handling state collisions in distributed systems.
+* **Global Error Formatting:** Moved `format_error_message` directly into the `RaiseError` middleware. Now, even manual `BugBunny::Client` requests will benefit from clean, structured exception messages (e.g., `"Internal Server Error - undefined method"`) optimized for APMs like Sentry or Datadog.
+
+## [3.1.2] - 2026-02-19
+
+### 🐛 Bug Fixes
+* **Controller Callback Inheritance:** Fixed a critical issue where `before_action`, `around_action`, and `rescue_from` definitions in a parent class (like `ApplicationController`) were not being inherited by child controllers. Migrated internal storage to `class_attribute` with deep duplication to ensure isolated, thread-safe inheritance without mutating the parent class.
+* **Gemspec Hygiene:** Updated the `spec.description` to resolve RubyGems identity warnings and added explicit minimum version boundaries for standard dependencies (e.g., `json >= 2.0`).
+
+### 🌟 Observability & DX (Developer Experience)
+* **Structured Remote Errors:** `BugBunny::Resource` now intelligently formats the body of remote errors. When raising a `ClientError` (4xx) or `InternalServerError` (500), it extracts the specific error message (e.g., `"Internal Server Error - undefined method 'foo'"`) or falls back to a readable JSON string. This drastically improves the legibility of remote stack traces in monitoring tools like Sentry or Datadog.
+* **Infrastructure Logging:** The `Consumer` and `Producer` now calculate the final resolved cascade options (`exchange_opts`, `queue_opts`) and explicitly log them during worker startup and message publishing. This provides absolute transparency into what configurations are actually reaching RabbitMQ.
+* **Consumer Cascade Options:** Added the `exchange_opts:` parameter to `Consumer.subscribe` to fully support Level 3 (On-the-fly) infrastructure configuration for manual worker instantiations.
+
+### 📖 Documentation
+* **Built-in Middlewares:** Added comprehensive documentation to the README explaining how to inject and utilize the provided `RaiseError` and `JsonResponse` middlewares when using the manual `BugBunny::Client`.
+
 ## [3.1.1] - 2026-02-19
 
 ### 🚀 Features

data/README.md

@@ -185,7 +185,27 @@ Manager::Service.with(
 ```
 
 ### 4. Client Middleware (Interceptores)
-Intercepta peticiones antes de salir hacia RabbitMQ. Ideal para inyectar Auth o Headers.
+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:
+
+* `BugBunny::Middleware::JsonResponse`: Parsea automáticamente el cuerpo de la respuesta de JSON a un Hash de Ruby.
+* `BugBunny::Middleware::RaiseError`: Evalúa el código de estado (`status`) de la respuesta y lanza excepciones nativas (`BugBunny::NotFound`, `BugBunny::UnprocessableEntity`, `BugBunny::InternalServerError`, etc.).
+
+```ruby
+# Uso con el cliente manual
+client = BugBunny::Client.new(pool: BUG_BUNNY_POOL) do |stack|
+  stack.use BugBunny::Middleware::RaiseError
+  stack.use BugBunny::Middleware::JsonResponse
+end
+
+# Ahora el cliente devolverá Hashes y lanzará errores si el worker falla
+response = client.request('users/1', method: :get)
+```
+
+**Middlewares Personalizados**
+Ideales para inyectar Auth o Headers de trazabilidad en todos los requests de un Recurso.
 
 ```ruby
 class Manager::Service < BugBunny::Resource
@@ -200,6 +220,30 @@ class Manager::Service < BugBunny::Resource
 end
 ```
 
+**Personalización Avanzada de Errores**
+Si en tu aplicación necesitas mapear códigos HTTP de negocio (ej. `402 Payment Required`) a excepciones personalizadas, la forma más limpia es usar `Module#prepend` sobre el middleware nativo en un inicializador. De esta forma inyectas tus reglas sin perder el comportamiento por defecto para los demás errores:
+
+```ruby
+# config/initializers/bug_bunny_custom_errors.rb
+module CustomBugBunnyErrors
+  def on_complete(response)
+    status = response['status'].to_i
+
+    # 1. Reglas específicas de tu negocio
+    if status == 402
+      raise MyApp::PaymentRequiredError, response['body']['message']
+    elsif status == 403 && response['body']['reason'] == 'ip_blocked'
+      raise MyApp::IpBlockedError, response['body']['detail']
+    end
+
+    # 2. Delegar el resto de los errores (404, 422, 500) al middleware original
+    super(response)
+  end
+end
+
+BugBunny::Middleware::RaiseError.prepend(CustomBugBunnyErrors)
+```
+
 ---
 
 ## 📡 Modo Servidor: Controladores

data/lib/bug_bunny/consumer.rb

@@ -53,15 +53,27 @@ module BugBunny
     # @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 exchange_opts [Hash] Opciones adicionales para el exchange (durable, auto_delete).
     # @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)
+    def subscribe(queue_name:, exchange_name:, routing_key:, exchange_type: 'direct', exchange_opts: {}, queue_opts: {}, block: true)
+      # Declaración de Infraestructura
+      x = session.exchange(name: exchange_name, type: exchange_type, opts: exchange_opts)
       q = session.queue(queue_name, queue_opts)
       q.bind(x, routing_key: routing_key)
 
-      BugBunny.configuration.logger.info("[BugBunny::Consumer] 🎧 Listening on '#{queue_name}' | Exchange: '#{exchange_name}' | Routing Key: '#{routing_key}'")
+      # 📊 LOGGING DE OBSERVABILIDAD: Calculamos las opciones finales para mostrarlas en consola
+      final_x_opts = BugBunny::Session::DEFAULT_EXCHANGE_OPTIONS
+                       .merge(BugBunny.configuration.exchange_options || {})
+                       .merge(exchange_opts || {})
+      final_q_opts = BugBunny::Session::DEFAULT_QUEUE_OPTIONS
+                       .merge(BugBunny.configuration.queue_options || {})
+                       .merge(queue_opts || {})
+
+      BugBunny.configuration.logger.info("[BugBunny::Consumer] 🎧 Listening on '#{queue_name}' (Opts: #{final_q_opts})")
+      BugBunny.configuration.logger.info("[BugBunny::Consumer] 🔀 Bounded to Exchange '#{exchange_name}' (#{exchange_type}) | Opts: #{final_x_opts} | RK: '#{routing_key}'")
+
       start_health_check(queue_name)
 
       q.subscribe(manual_ack: true, block: block) do |delivery_info, properties, body|

data/lib/bug_bunny/controller.rb

@@ -7,99 +7,146 @@ require 'active_support/core_ext/class/attribute'
 module BugBunny
   # Clase base para todos los Controladores de Mensajes en BugBunny.
   #
+  # Actúa como el receptor final de los mensajes enrutados desde el consumidor.
+  # Implementa un ciclo de vida similar a ActionController en Rails, soportando:
+  # - Filtros (`before_action`, `around_action`).
+  # - Manejo declarativo de errores (`rescue_from`).
+  # - Parsing de parámetros unificados (`params`).
+  # - Respuestas estructuradas (`render`).
+  #
   # @author Gabriel
   # @since 3.0.6
   class Controller
     include ActiveModel::Model
     include ActiveModel::Attributes
 
-    # @return [Hash] Metadatos del mensaje entrante.
+    # @!group Atributos de Instancia
+
+    # @return [Hash] Metadatos del mensaje entrante (ej. HTTP method, routing_key, id).
     attribute :headers
 
-    # @return [ActiveSupport::HashWithIndifferentAccess] Parámetros unificados.
+    # @return [ActiveSupport::HashWithIndifferentAccess] Parámetros unificados (Body JSON + Query String).
     attribute :params
 
-    # @return [String] Cuerpo crudo.
+    # @return [String] Cuerpo crudo original en caso de no ser JSON.
     attribute :raw_string
 
-    # @return [Hash] Headers de respuesta.
+    # @return [Hash] Headers de respuesta que serán enviados de vuelta en RPC.
     attr_reader :response_headers
 
-    # @return [Hash, nil] Respuesta renderizada.
+    # @return [Hash, nil] Respuesta final renderizada.
     attr_reader :rendered_response
 
-    # --- INFRAESTRUCTURA DE FILTROS (DEFINICIÓN) ---
-    # Deben definirse ANTES de ser usados por la configuración de logs.
+    # @!endgroup
 
-    # @api private
-    def self.before_actions
-      @before_actions ||= Hash.new { |h, k| h[k] = [] }
-    end
 
-    # @api private
-    def self.around_actions
-      @around_actions ||= Hash.new { |h, k| h[k] = [] }
-    end
+    # ==========================================
+    # INFRAESTRUCTURA DE FILTROS Y LOGS (HEREDABLES)
+    # ==========================================
+
+    # Usamos `class_attribute` con `default` para garantizar la herencia correcta
+    # hacia las subclases (ej. de ApplicationController a ServicesController).
+    class_attribute :before_actions, default: {}
+    class_attribute :around_actions, default: {}
+    class_attribute :log_tags, default: []
+    class_attribute :rescue_handlers, default: []
 
     # Registra un filtro que se ejecutará **antes** de la acción.
+    # Si el filtro invoca `render`, la cadena se interrumpe y la acción no se ejecuta.
+    #
+    # @param method_name [Symbol] Nombre del método privado a ejecutar.
+    # @param options [Hash] Opciones como `only: [:show, :update]`.
+    # @return [void]
     def self.before_action(method_name, **options)
-      register_callback(before_actions, method_name, options)
+      register_callback(:before_actions, method_name, options)
     end
 
     # Registra un filtro que **envuelve** la ejecución de la acción.
+    # El método registrado debe invocar `yield` para continuar la ejecución.
+    #
+    # @param method_name [Symbol] Nombre del método privado a ejecutar.
+    # @param options [Hash] Opciones como `only: [:index]`.
+    # @return [void]
     def self.around_action(method_name, **options)
-      register_callback(around_actions, method_name, options)
+      register_callback(:around_actions, method_name, options)
     end
 
-    # Helper interno para registrar callbacks.
-    def self.register_callback(collection, method_name, options)
-      only = Array(options[:only]).map(&:to_sym)
-      target_actions = only.empty? ? [:_all_actions] : only
-      target_actions.each { |action| collection[action] << method_name }
+    # Manejo declarativo de excepciones.
+    # Atrapa errores específicos que ocurran durante la ejecución de la acción.
+    #
+    # @example
+    #   rescue_from Api::Error::NotFound, with: :render_not_found
+    #   rescue_from StandardError do |e|
+    #     render status: 500, json: { error: e.message }
+    #   end
+    #
+    # @param klasses [Array<Class, String>] Clases de excepciones a atrapar.
+    # @param with [Symbol, nil] Nombre del método manejador.
+    # @yield [Exception] Bloque opcional para manejar el error inline.
+    # @raise [ArgumentError] Si no se provee un manejador (with o block).
+    def self.rescue_from(*klasses, with: nil, &block)
+      handler = with || block
+      raise ArgumentError, "Need a handler. Supply 'with: :method' or a block." unless handler
+
+      # Duplicamos el array del padre para no mutarlo al registrar reglas en el hijo
+      new_handlers = self.rescue_handlers.dup
+
+      klasses.each do |klass|
+        new_handlers.unshift([klass, handler])
+      end
+
+      self.rescue_handlers = new_handlers
     end
 
-    # --- CONFIGURACIÓN DE LOGGING ---
+    # Helper interno para registrar callbacks garantizando Thread-Safety e Inmutabilidad del padre.
+    # @api private
+    def self.register_callback(collection_name, method_name, options)
+      current_hash = send(collection_name)
 
-    # Define los tags que se antepondrán a cada línea de log.
-    class_attribute :log_tags
-    self.log_tags = []
+      # Deep dup: Clonamos el hash y sus arrays internos para no modificar la clase padre
+      new_hash = current_hash.transform_values(&:dup)
 
-    # AHORA SÍ: Podemos llamar a around_action porque ya fue definido arriba.
-    around_action :apply_log_tags
+      only = Array(options[:only]).map(&:to_sym)
+      target_actions = only.empty? ? [:_all_actions] : only
 
-    # --- INICIALIZACIÓN ---
+      target_actions.each do |action|
+        new_hash[action] ||= []
+        new_hash[action] << method_name
+      end
 
-    def initialize(attributes = {})
-      super
-      @response_headers = {}
+      send("#{collection_name}=", new_hash)
     end
 
-    # --- MANEJO DE ERRORES ---
+    # Aplicamos automáticamente las etiquetas de logs a todas las acciones.
+    around_action :apply_log_tags
 
-    # @api private
-    def self.rescue_handlers
-      @rescue_handlers ||= []
-    end
 
-    def self.rescue_from(*klasses, with: nil, &block)
-      handler = with || block
-      raise ArgumentError, "Need a handler. Supply 'with: :method' or a block." unless handler
+    # ==========================================
+    # INICIALIZACIÓN Y CICLO DE VIDA
+    # ==========================================
 
-      klasses.each do |klass|
-        rescue_handlers.unshift([klass, handler])
-      end
+    def initialize(attributes = {})
+      super
+      @response_headers = {}
     end
 
-    # --- PIPELINE DE EJECUCIÓN ---
-
+    # Punto de entrada principal estático llamado por el Router (`BugBunny::Consumer`).
+    #
+    # @param headers [Hash] Metadatos y variables de enrutamiento.
+    # @param body [String, Hash] El payload del mensaje AMQP.
+    # @return [Hash] Respuesta final estructurada.
     def self.call(headers:, body: {})
       new(headers: headers).process(body)
     end
 
+    # Ejecuta el ciclo de vida completo de la petición: Params -> Before -> Action -> Rescue.
+    #
+    # @param body [String, Hash] El cuerpo del mensaje.
+    # @return [Hash] La respuesta lista para ser enviada vía RabbitMQ RPC.
     def process(body)
       prepare_params(body)
 
-      # Inyección de configuración global de logs si no hay específica
+      # Inyección de configuración global de logs si el controlador no define propios
       if self.class.log_tags.empty? && BugBunny.configuration.log_tags.any?
         self.class.log_tags = BugBunny.configuration.log_tags
       end
@@ -118,15 +165,14 @@ module BugBunny
         end
       end
 
-      # Construir la cadena de responsabilidad
+      # Construir e invocar la cadena de responsabilidad (Middlewares/Around Actions)
       execution_chain = current_arounds.reverse.inject(core_execution) do |next_step, method_name|
         lambda { send(method_name, &next_step) }
       end
 
-      # Ejecutar la cadena
       execution_chain.call
 
-      # Respuesta final
+      # Si no hubo renderización explícita, devuelve 204 No Content
       rendered_response || { status: 204, headers: response_headers, body: nil }
 
     rescue StandardError => e
@@ -135,21 +181,14 @@ module BugBunny
 
     private
 
-    # --- HELPERS INTERNOS ---
-
-    def resolve_callbacks(collection, action_name)
-      (collection[:_all_actions] || []) + (collection[action_name] || [])
-    end
-
-    def run_before_actions(action_name)
-      current_befores = resolve_callbacks(self.class.before_actions, action_name)
-      current_befores.uniq.each do |method_name|
-        send(method_name)
-        return false if rendered_response
-      end
-      true
-    end
+    # ==========================================
+    # HELPERS INTERNOS
+    # ==========================================
 
+    # Evalúa la excepción lanzada y busca el manejador más adecuado definido en `rescue_from`.
+    #
+    # @param exception [StandardError] La excepción atrapada.
+    # @return [Hash] Respuesta de error renderizada.
     def handle_exception(exception)
       handler_entry = self.class.rescue_handlers.find do |klass, _|
         if klass.is_a?(String)
@@ -161,24 +200,34 @@ module BugBunny
 
       if handler_entry
         _, handler = handler_entry
-        if handler.is_a?(Symbol); send(handler, exception)
-        elsif handler.respond_to?(:call); instance_exec(exception, &handler)
+        if handler.is_a?(Symbol)
+          send(handler, exception)
+        elsif handler.respond_to?(:call)
+          instance_exec(exception, &handler)
         end
         return rendered_response if rendered_response
       end
 
+      # Fallback genérico si la excepción no fue mapeada
       BugBunny.configuration.logger.error("[BugBunny::Controller] 💥 Unhandled Exception (#{exception.class}): #{exception.message}")
-      BugBunny.configuration.logger.error(exception.backtrace.first(5).join("\n")) # Limitamos a 5 líneas para no ensuciar
+      BugBunny.configuration.logger.error(exception.backtrace.first(5).join("\n"))
 
       {
         status: 500,
         headers: response_headers,
-        body: { error: exception.message, type: exception.class.name }
+        body: { error: "Internal Server Error", detail: exception.message, type: exception.class.name }
       }
     end
 
+    # Renderiza una respuesta que será enviada de vuelta por la cola reply-to.
+    #
+    # @param status [Symbol, Integer] Código HTTP (ej. :ok, :not_found, 201).
+    # @param json [Object] El payload a serializar como JSON.
+    # @return [Hash] La estructura renderizada interna.
     def render(status:, json: nil)
-      code = Rack::Utils::SYMBOL_TO_STATUS_CODE[status] || 200
+      code = Rack::Utils::SYMBOL_TO_STATUS_CODE[status] || status.to_i
+      code = 200 if code.zero? # Fallback de seguridad
+
       @rendered_response = {
         status: code,
         headers: response_headers,
@@ -186,21 +235,43 @@ module BugBunny
       }
     end
 
+    # Unifica el query string, parámetros de ruta y el body JSON en un solo objeto `params`.
     def prepare_params(body)
       self.params = {}.with_indifferent_access
+
       params.merge!(headers[:query_params]) if headers[:query_params].present?
       params[:id] = headers[:id] if headers[:id].present?
 
       if body.is_a?(Hash)
         params.merge!(body)
       elsif body.is_a?(String) && headers[:content_type].to_s.include?('json')
-        parsed = JSON.parse(body) rescue nil
+        parsed = begin
+                   JSON.parse(body)
+                 rescue JSON::ParserError
+                   nil
+                 end
         params.merge!(parsed) if parsed
       else
         self.raw_string = body
       end
     end
 
+    # Obtiene la lista combinada de callbacks globales y específicos para una acción.
+    def resolve_callbacks(collection, action_name)
+      (collection[:_all_actions] || []) + (collection[action_name] || [])
+    end
+
+    # Ejecuta secuencialmente todos los before_actions.
+    # Si alguno invoca render(), detiene el flujo devolviendo `false`.
+    def run_before_actions(action_name)
+      current_befores = resolve_callbacks(self.class.before_actions, action_name)
+      current_befores.uniq.each do |method_name|
+        send(method_name)
+        return false if rendered_response
+      end
+      true
+    end
+
     # --- LÓGICA DE LOGGING ENCAPSULADA ---
 
     def apply_log_tags
@@ -225,6 +296,7 @@ module BugBunny
       end.compact
     end
 
+    # @return [String] Identificador único de trazabilidad de la petición.
     def uuid
       headers[:correlation_id] || headers['X-Request-Id']
     end

data/lib/bug_bunny/exception.rb

@@ -1,4 +1,5 @@
-# lib/bug_bunny/exception.rb
+# frozen_string_literal: true
+
 require 'json'
 
 module BugBunny
@@ -11,10 +12,12 @@ module BugBunny
   class CommunicationError < Error; end
 
   # Error lanzado cuando ocurren un acceso no permitido a controladores.
-  # Suele envolver excepciones nativas de la gema `bunny` (ej: TCP connection failure).
+  # Protege contra vulnerabilidades de RCE validando la herencia de las clases enrutadas.
   class SecurityError < Error; end
 
-  # === Categoría: Errores del Cliente (4xx) ===
+  # ==========================================
+  # Categoría: Errores del Cliente (4xx)
+  # ==========================================
 
   # Clase base para errores causados por una petición incorrecta del cliente.
   # Corresponde a códigos de estado 400-499.
@@ -36,7 +39,13 @@ module BugBunny
   # El servidor tardó demasiado en responder o el cliente agotó su tiempo de espera (RPC timeout).
   class RequestTimeout < ClientError; end
 
-  # === Categoría: Errores del Servidor (5xx) ===
+  # Error 409: Conflict.
+  # implica que la petición es técnicamente válida, pero choca con reglas de negocio o datos existentes
+  class Conflict < ClientError; end
+
+  # ==========================================
+  # Categoría: Errores del Servidor (5xx)
+  # ==========================================
 
   # Clase base para errores causados por fallos en el servidor remoto.
   # Corresponde a códigos de estado 500-599.
@@ -46,44 +55,59 @@ module BugBunny
   # Ocurrió un error inesperado en el worker/servidor remoto al procesar el mensaje.
   class InternalServerError < ServerError; end
 
-  # === Categoría: Errores de Validación (422) ===
+  # ==========================================
+  # Categoría: Errores de Validación (422)
+  # ==========================================
 
   # Error 422: Unprocessable Entity.
   # Indica que la solicitud fue bien formada pero contenía errores semánticos,
   # típicamente fallos de validación en el modelo remoto (ActiveRecord).
   #
-  # Esta excepción es especial porque intenta parsear automáticamente el cuerpo de la respuesta
-  # para exponer los mensajes de error de forma estructurada.
+  # Esta excepción es "inteligente": intenta parsear automáticamente el cuerpo 
+  # de la respuesta para extraer y exponer los mensajes de error de forma estructurada,
+  # buscando por convención la clave `errors`.
   class UnprocessableEntity < ClientError
-    # @return [Hash, Array] Los mensajes de error parseados desde la respuesta.
+    # @return [Hash, Array, String] Los mensajes de error listos para ser iterados.
     attr_reader :error_messages
 
-    # @return [String] El cuerpo crudo de la respuesta original.
+    # @return [String, Hash] El cuerpo crudo de la respuesta original.
     attr_reader :raw_response
 
     # Inicializa la excepción procesando el cuerpo de la respuesta.
     #
-    # @param response_body [String, Hash] El cuerpo de la respuesta fallida.
+    # @param response_body [String, Hash] El cuerpo de la respuesta fallida (ej. `{ "errors": { "name": ["blank"] } }`).
     def initialize(response_body)
       @raw_response = response_body
-      @error_messages = parse_errors(response_body)
+      @error_messages = extract_errors(response_body)
       super('Validation failed on remote service')
     end
 
     private
 
-    # Intenta convertir el cuerpo de la respuesta a una estructura Ruby (Hash/Array).
-    # Si el cuerpo no es JSON válido, retorna un Hash vacío para evitar excepciones anidadas.
+    # Intenta convertir el cuerpo de la respuesta a una estructura Ruby y extrae la clave 'errors'.
+    # Si el cuerpo no sigue la convención o no es JSON, hace un graceful fallback devolviendo
+    # el payload completo.
     #
-    # @param body [String, Hash] El cuerpo a parsear.
-    # @return [Object] El cuerpo parseado o un Hash vacío si falla.
+    # @param body [String, Hash] El cuerpo a procesar.
+    # @return [Object] Los errores aislados o el cuerpo original.
     # @api private
-    def parse_errors(body)
-      return body if body.is_a?(Hash)
-
-      JSON.parse(body)
-    rescue JSON::ParserError
-      {}
+    def extract_errors(body)
+      parsed = if body.is_a?(String)
+                 begin
+                   JSON.parse(body)
+                 rescue JSON::ParserError
+                   body # Si no es JSON, devolvemos el string tal cual
+                 end
+               else
+                 body
+               end
+
+      if parsed.is_a?(Hash)
+        # Extraemos inteligentemente la clave 'errors' si existe (convención típica de Rails)
+        parsed['errors'] || parsed[:errors] || parsed
+      else
+        parsed
+      end
     end
   end
 end

data/lib/bug_bunny/middleware/raise_error.rb

@@ -1,22 +1,33 @@
-# lib/bug_bunny/middleware/raise_error.rb
 # frozen_string_literal: true
 
-require_relative '../middleware/base'
+require_relative 'base'
 
 module BugBunny
   module Middleware
     # Middleware que inspecciona el status de la respuesta y lanza excepciones
     # si se encuentran errores (4xx o 5xx).
     #
+    # Extrae inteligentemente el mensaje de error del cuerpo de la respuesta
+    # para que las excepciones tengan trazas claras y legibles, evitando el
+    # output crudo de Hashes en Ruby (`{ "error" => ... }`).
+    #
     # @see BugBunny::Middleware::Base
     class RaiseError < BugBunny::Middleware::Base
       # Hook de ciclo de vida: Ejecutado después de recibir la respuesta.
       #
-      # Verifica el código de estado y lanza la excepción correspondiente.
+      # Verifica el código de estado (status) de la respuesta. Si cae en el rango
+      # de éxito (2xx), permite que el flujo continúe. Si es un error, lo formatea
+      # y lanza la excepción semántica correspondiente.
       #
       # @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.
+      # @raise [BugBunny::BadRequest] Si el status es 400.
+      # @raise [BugBunny::NotFound] Si el status es 404.
+      # @raise [BugBunny::NotAcceptable] Si el status es 406.
+      # @raise [BugBunny::RequestTimeout] Si el status es 408.
+      # @raise [BugBunny::Conflict] Si el status es 409.
+      # @raise [BugBunny::UnprocessableEntity] Si el status es 422.
+      # @raise [BugBunny::InternalServerError] Si el status es 500..599.
+      # @raise [BugBunny::ClientError, BugBunny::ServerError] Para códigos no mapeados.
       # @return [void]
       def on_complete(response)
         status = response['status'].to_i
@@ -24,25 +35,64 @@ module BugBunny
 
         case status
         when 200..299
-          nil # OK
-        when 400 then raise BugBunny::BadRequest, body
-        when 404 then raise BugBunny::NotFound
-        when 406 then raise BugBunny::NotAcceptable
-        when 408 then raise BugBunny::RequestTimeout
-        when 422 then raise BugBunny::UnprocessableEntity, body
-        when 500 then raise BugBunny::InternalServerError, body
+          return # Flujo normal (Success)
+        when 400
+          raise BugBunny::BadRequest, format_error_message(body)
+        when 404
+          raise BugBunny::NotFound
+        when 406
+          raise BugBunny::NotAcceptable
+        when 408
+          raise BugBunny::RequestTimeout
+        when 409
+          raise BugBunny::Conflict, format_error_message(body)
+        when 422
+          # Pasamos el body crudo; UnprocessableEntity lo procesará en exception.rb
+          raise BugBunny::UnprocessableEntity, body
+        when 500..599
+          raise BugBunny::InternalServerError, format_error_message(body)
         else
-          handle_unknown_error(status)
+          handle_unknown_error(status, body)
         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
+      # Formatea el cuerpo de la respuesta de error para que sea legible en las excepciones.
+      #
+      # Prioriza la convención `{ "error": "...", "detail": "..." }`. Si la respuesta no
+      # sigue esta convención, convierte el Hash completo a un JSON string para mantenerlo legible.
+      #
+      # @param body [Hash, String, nil] El cuerpo de la respuesta.
+      # @return [String] Un mensaje de error limpio y estructurado.
+      def format_error_message(body)
+        return "Unknown Error" if body.nil? || (body.respond_to?(:empty?) && body.empty?)
+        return body if body.is_a?(String)
+
+        # Si el worker devolvió un JSON con una key 'error' (nuestra convención en Controller)
+        if body.is_a?(Hash) && body['error']
+          detail = body['detail'] ? " - #{body['detail']}" : ""
+          "#{body['error']}#{detail}"
+        else
+          # Fallback: Convertir todo el Hash a JSON string para que se vea claro en Sentry/Logs
+          body.to_json
+        end
+      end
+
+      # Maneja códigos de error genéricos no mapeados explícitamente en el `case`.
+      #
+      # @param status [Integer] El código de estado HTTP (ej. 418, 502).
+      # @param body [Object] El cuerpo crudo de la respuesta.
+      # @raise [BugBunny::ServerError] Si es 5xx.
+      # @raise [BugBunny::ClientError] Si es 4xx.
+      def handle_unknown_error(status, body)
+        msg = format_error_message(body)
+
+        if status >= 500
+          raise BugBunny::ServerError, "Server Error (#{status}): #{msg}"
+        elsif status >= 400
+          raise BugBunny::ClientError, "Client Error (#{status}): #{msg}"
+        end
       end
     end
   end

data/lib/bug_bunny/producer.rb

@@ -91,16 +91,26 @@ module BugBunny
 
     private
 
+    # Registra la petición en el log calculando las opciones de infraestructura.
+    #
+    # @param request [BugBunny::Request] Objeto Request que se está enviando.
+    # @param payload [String] El cuerpo del mensaje serializado.
     def log_request(request, payload)
       verb = request.method.to_s.upcase
       target = request.path
       rk = request.final_routing_key
       id = request.correlation_id
 
+      # 📊 LOGGING DE OBSERVABILIDAD: Calculamos las opciones finales para mostrarlas en consola
+      final_x_opts = BugBunny::Session::DEFAULT_EXCHANGE_OPTIONS
+                       .merge(BugBunny.configuration.exchange_options || {})
+                       .merge(request.exchange_options || {})
+
       # INFO: Resumen de una línea (Traffic)
       BugBunny.configuration.logger.info("[BugBunny::Producer] 📤 #{verb} /#{target} | RK: '#{rk}' | ID: #{id}")
 
-      # DEBUG: Detalle completo (Payload)
+      # DEBUG: Detalle completo de Infraestructura y Payload
+      BugBunny.configuration.logger.debug("[BugBunny::Producer] ⚙️  Exchange Opts: #{final_x_opts}")
       BugBunny.configuration.logger.debug("[BugBunny::Producer] 📦 Payload: #{payload.truncate(300)}") if payload.is_a?(String)
     end
 

data/lib/bug_bunny/resource.rb

@@ -15,7 +15,7 @@ module BugBunny
   # 3. **Específico:** Definidos en la clase del recurso o vía `with`.
   #
   # @author Gabriel
-  # @since 3.1.0
+  # @since 3.1.2
   class Resource
     include ActiveModel::API
     include ActiveModel::Attributes
@@ -100,13 +100,22 @@ module BugBunny
         stack
       end
 
-      # Instancia el cliente inyectando los middlewares configurados.
+      # Instancia el cliente inyectando los middlewares núcleo y personalizados.
+      # Integra automáticamente `RaiseError` y `JsonResponse` para que el ORM trabaje
+      # puramente con datos parseados o atrape excepciones sin validar HTTP Status manuales.
+      #
       # @return [BugBunny::Client]
       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) }
+
+        BugBunny::Client.new(pool: pool) do |stack|
+          # 1. Middlewares Core (Siempre presentes para el Resource)
+          stack.use BugBunny::Middleware::RaiseError
+          stack.use BugBunny::Middleware::JsonResponse
+
+          # 2. Middlewares Personalizados del Usuario
+          resolve_middleware_stack.each { |block| block.call(stack) }
         end
       end
 
@@ -164,6 +173,8 @@ module BugBunny
       # @!group Acciones CRUD RESTful
 
       # Realiza una búsqueda filtrada (GET).
+      # Mapea un posible 404 a un array vacío.
+      #
       # @param filters [Hash]
       # @return [Array<BugBunny::Resource>]
       def where(filters = {})
@@ -188,6 +199,8 @@ module BugBunny
           inst.send(:clear_changes_information)
           inst
         end
+      rescue BugBunny::NotFound
+        []
       end
 
       # Devuelve todos los registros.
@@ -195,6 +208,8 @@ module BugBunny
       def all; where({}); end
 
       # Busca un registro por ID (GET).
+      # Mapea un 404 (NotFound) devolviendo un objeto nulo.
+      #
       # @param id [String, Integer]
       # @return [BugBunny::Resource, nil]
       def find(id)
@@ -211,12 +226,14 @@ module BugBunny
           queue_options: current_queue_options
         )
 
-        return nil if response.nil? || response['status'] == 404
-        return nil unless response['body'].is_a?(Hash)
+        return nil unless response && response['body'].is_a?(Hash)
+
         instance = new(response['body'])
         instance.persisted = true
         instance.send(:clear_changes_information)
         instance
+      rescue BugBunny::NotFound
+        nil
       end
 
       # Crea una nueva instancia y la persiste.
@@ -350,7 +367,9 @@ module BugBunny
     # @!group Persistencia
 
     # Guarda el recurso en el servidor remoto vía AMQP (POST o PUT).
-    # @return [Boolean]
+    # Asume el Happy Path; el middleware se encarga de interceptar y lanzar excepciones.
+    #
+    # @return [Boolean] Retorna true si tuvo éxito, false si falló la validación.
     def save
       return false unless valid?
 
@@ -364,6 +383,7 @@ module BugBunny
         path = is_new ? self.class.resource_name : "#{self.class.resource_name}/#{id}"
         method = is_new ? :post : :put
 
+        # Si el middleware de errores no lanza excepción, asumimos un éxito (200..299)
         response = bug_bunny_client.request(
           path,
           method: method,
@@ -375,7 +395,10 @@ module BugBunny
           body: wrapped_payload
         )
 
-        handle_save_response(response)
+        assign_attributes(response['body'])
+        self.persisted = true
+        clear_changes_information
+        true
       end
     rescue BugBunny::UnprocessableEntity => e
       load_remote_rabbit_errors(e.error_messages)
@@ -383,6 +406,7 @@ module BugBunny
     end
 
     # Elimina el recurso del servidor remoto (DELETE).
+    #
     # @return [Boolean]
     def destroy
       return false unless persisted?
@@ -409,25 +433,9 @@ module BugBunny
 
     private
 
-    # Maneja la lógica de respuesta para la acción de guardado.
-    def handle_save_response(response)
-      if response['status'] == 422
-        raise BugBunny::UnprocessableEntity.new(response['body']['errors'] || response['body'])
-      elsif response['status'] >= 500
-        raise BugBunny::InternalServerError
-      elsif response['status'] >= 400
-        raise BugBunny::ClientError
-      end
-
-      assign_attributes(response['body'])
-      self.persisted = true
-      clear_changes_information
-      true
-    end
-
-    # Carga errores remotos en el objeto local.
+    # Carga errores remotos en el objeto local (utilizado al recibir 422).
     def load_remote_rabbit_errors(errors_hash)
-      return if errors_hash.nil?
+      return if errors_hash.nil? || errors_hash.empty?
       if errors_hash.is_a?(String)
         errors.add(:base, errors_hash)
       else

data/lib/bug_bunny/version.rb

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

data/test/test_helper.rb

@@ -2,7 +2,7 @@
 
 require 'bundler/setup'
 require 'minitest/autorun'
-# require 'minitest/reporters' 
+# require 'minitest/reporters'
 require 'bug_bunny'
 require 'connection_pool'
 require 'securerandom'
@@ -14,7 +14,7 @@ BugBunny.configure do |config|
   config.password = ENV.fetch('RABBITMQ_PASS', 'guest')
   config.vhost = '/'
   config.logger = Logger.new($stdout)
-  config.logger.level = Logger::WARN 
+  config.logger.level = Logger::WARN
 
   # ========================================================
   # LA MAGIA DE LA CASCADA (Nivel 2: Configuración Global)
@@ -38,10 +38,10 @@ module IntegrationHelper
 
   def with_running_worker(queue:, exchange:, exchange_type: 'topic', routing_key: '#')
     conn = BugBunny.create_connection
-    
+
     worker_thread = Thread.new do
       ch = conn.create_channel
-      
+
       x_opts = BugBunny.configuration.exchange_options || {}
       q_opts = BugBunny.configuration.queue_options || {}
 
@@ -63,7 +63,7 @@ module IntegrationHelper
       puts e.backtrace.join("\n")
     end
 
-    sleep 0.5 
+    sleep 0.5
     yield
   ensure
     conn&.close
@@ -74,26 +74,26 @@ module IntegrationHelper
   def with_spy_worker(queue:, exchange:, exchange_type: 'topic', routing_key: '#')
     captured_messages = Thread::Queue.new
     conn = BugBunny.create_connection
-    
+
     worker_thread = Thread.new do
       ch = conn.create_channel
-      
+
       x_opts = BugBunny.configuration.exchange_options || {}
       q_opts = BugBunny.configuration.queue_options || {}
-      
+
       # FIX DEFINITIVO: Ahora 'x' es un hermoso objeto Bunny::Exchange
       # que la función .bind() entiende perfectamente.
       x = ch.public_send(exchange_type, exchange, x_opts)
       q = ch.queue(queue, q_opts)
-      
+
       # Bindeamos el objeto al queue
       q.bind(x, routing_key: routing_key)
 
       q.subscribe(block: true) do |delivery, props, body|
-        captured_messages << { 
-          body: body, 
+        captured_messages << {
+          body: body,
           routing_key: delivery.routing_key,
-          headers: props.headers 
+          headers: props.headers
         }
       end
     rescue => e

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bug_bunny
 version: !ruby/object:Gem::Version
-  version: 3.1.1
+  version: 3.1.3
 platform: ruby
 authors:
 - gabix