bug_bunny 3.1.2 → 3.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 297dacbda238ba5789ff56e5869302a851d15011cd43cb873b9eb3ece129c797
-  data.tar.gz: 0cc109f779f574e29f6dd96d0b41e3b956397db4eca2e0476d39ab6d5e96e877
+  metadata.gz: 4aab7949b09bfbf861d4a9ff736bc3bef832fdb3c8a302924544783bdbc9e1bf
+  data.tar.gz: 12b73641a812ec4ce72d2a5ad8992a1f2b91c4b0b11ce181aac02fe3a4912751
 SHA512:
-  metadata.gz: 8b7850f2ca72f08f76823a0cf8a1b8845ab9ec831b5e26ba994bffcf88e41d5163351679690a0fd993aea81f9dbdc5344c2558ac28a0daffe98ae5f8e83acdf6
-  data.tar.gz: 834d477e56ccf027eea1009813b8e38536d1ea0f49fd40f95070f9db314a3b29550613b2fa4bdda3fc4562d994d404f7123ca6d526ac3b886e2f509d046506ec
+  metadata.gz: 2f4475f1754c1de91be6576d4fabb23d025b1f3735d4d76d3123415e71b907d2bfc307dd8e8f4a921ad5a11b2524cd85a1ee17ea3fb1d42f6e15c62ddef01425
+  data.tar.gz: c3973288d2d394121491ffb3c7fa809b8841c9fdc3fc87486fb807b62b6f948e48298fd9f4b696132c9b86d448dad82bd4cfa909c39384efc2ab1b7729c15f31

data/CHANGELOG.md

@@ -1,4 +1,15 @@
 # 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

data/README.md

@@ -188,7 +188,7 @@ Manager::Service.with(
 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 errores ya está integrado. Pero si utilizas el cliente manual (`BugBunny::Client`), puedes inyectar los middlewares incluidos para no tener que parsear respuestas manualmente:
+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.).
@@ -220,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/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/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,40 +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, format_error_message(response['body'])
-      elsif response['status'] >= 400
-        raise BugBunny::ClientError, format_error_message(response['body'])
-      end
-
-      assign_attributes(response['body'])
-      self.persisted = true
-      clear_changes_information
-      true
-    end
-
-    # Formatea el cuerpo de la respuesta de error para que sea legible en las excepciones
-    def format_error_message(body)
-      return "Unknown Error" if body.nil?
-      return body if body.is_a?(String)
-
-      # Si el worker devolvió un JSON con una key 'error' (nuestra convención en Controller), la priorizamos
-      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
-
-    # 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.2"
+  VERSION = "3.1.3"
 end

metadata

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