bug_bunny 3.0.3 → 3.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d012f3384230432e8f94c365d2a19ea05179f362f0433482c8d9967c3838102
-  data.tar.gz: ae306fdebe3c63b08a4980337294e46830a0277c9deea509a485d9978b2a9760
+  metadata.gz: 4752202964e5f4382a685a356a31264db3ae51049c42a49d3e5a6602fda10ed1
+  data.tar.gz: 1cb2f414e1fb52560d9a4310fd0679c1a59f86dc072fce6dd385b17006ecc6a0
 SHA512:
-  metadata.gz: fdee3c4b42d2e852649985f962fe81ca0cf3b152357d484e3e37310bbacd07889c82408c92b3b99936c0f81d2cf60e22ca57bae24f54e30efb0a36040649382b
-  data.tar.gz: 4c47cde21b912b1cad5cda132af21cb7ea5fcb0a7cefd8827f572695fbe50d6945b6083738e81fa8cc3f40b03344314f28655586e7c298925b2bf9482034acaa
+  metadata.gz: 74af2e635f79d182cfe0fc336a67bf5175ad02729e39b5ddb77fb6bfdde4e3e733f863c78e453160ca6e03ff381dc81f1169a1c9d7be39a116d971638f61d846
+  data.tar.gz: c7da63dcce1cc2f0b77faa253327ddb4eec88866328429e84383172e07be402ff9d9c2ca6a2fbe16e9c0f7762bd8119c17496caa37a4ad35d0be07867e8aa78c

data/CHANGELOG.md

@@ -1,4 +1,13 @@
 # Changelog
+## [3.0.4] - 2026-02-16
+
+### ♻️ Refactoring & Architecture
+* **Middleware Architecture Overhaul:** Refactored the internal middleware stack to follow the **Template Method** pattern (Faraday-style).
+    * **New Base Class:** Introduced `BugBunny::Middleware` to standardize the execution flow (`call`, `app.call`).
+    * **Lifecycle Hooks:** Middlewares can now simply implement `on_request(env)` and/or `on_complete(response)` methods, eliminating the need to manually manage the execution chain.
+    * **Core Middlewares:** Refactored `RaiseError` and `JsonResponse` to use this new pattern, resulting in cleaner and more maintainable code.
+    * This change is **fully backward compatible** and paves the way for future middlewares (Loggers, Tracing, Headers injection).
+
 ## [3.0.3] - 2026-02-13
 
 ### 🐛 Bug Fixes

data/lib/bug_bunny/middleware/json_response.rb

@@ -1,73 +1,62 @@
 # lib/bug_bunny/middleware/json_response.rb
+# frozen_string_literal: true
+
 require 'json'
+require_relative '../middleware'
 
 module BugBunny
   module Middleware
     # Middleware encargado de parsear automáticamente el cuerpo de la respuesta.
     #
-    # Este middleware intercepta la respuesta proveniente del servicio remoto. Si el `body`
-    # es un String JSON válido, lo convierte a un Hash o Array de Ruby.
-    #
-    # **Integración con Rails:**
-    # Si `ActiveSupport` está cargado en el entorno, convierte los Hashes resultantes
-    # a `HashWithIndifferentAccess`. Esto permite a los desarrolladores acceder a las claves
-    # usando símbolos o strings indistintamente (ej: `body[:id]` o `body['id']`),
-    # comportamiento estándar en Rails.
+    # Convierte strings JSON en Hashes de Ruby. Si está disponible ActiveSupport,
+    # aplica HashWithIndifferentAccess.
     #
-    # @example Uso en la configuración del cliente
-    #   client = BugBunny::Client.new(pool: POOL) do |conn|
-    #     # Se recomienda ponerlo después de RaiseError para tener el body parseado en las excepciones
-    #     conn.use BugBunny::Middleware::RaiseError
-    #     conn.use BugBunny::Middleware::JsonResponse
-    #   end
-    class JsonResponse
-      # Inicializa el middleware.
-      #
-      # @param app [Object] El siguiente middleware o el productor final en el stack.
-      def initialize(app)
-        @app = app
-      end
-
-      # Ejecuta el middleware.
+    # @see BugBunny::Middleware
+    class JsonResponse < BugBunny::Middleware
+      # Hook de ciclo de vida: Ejecutado después de recibir la respuesta.
       #
-      # Invoca al siguiente eslabón (`@app.call`) y espera su retorno.
-      # Una vez recibida la respuesta, procesa el `body` antes de devolverla hacia arriba en la cadena.
+      # Intercepta el body y lo reemplaza por su versión parseada.
       #
-      # @param env [BugBunny::Request] El objeto request actual (el entorno).
-      # @return [Hash] La respuesta con el campo 'body' transformado (si era JSON).
-      def call(env)
-        response = @app.call(env)
-        # Parseamos el body DESPUÉS de recibir la respuesta (Post-processing)
+      # @param response [Hash] La respuesta cruda.
+      # @return [void]
+      def on_complete(response)
         response['body'] = parse_body(response['body'])
-        response
       end
 
+      private
+
       # Intenta convertir el cuerpo de la respuesta a una estructura Ruby nativa.
       #
-      # @param body [String, Hash, Array, nil] El cuerpo original de la respuesta.
-      # @return [Object] El cuerpo parseado (Hash/Array) o el objeto original si falla el parseo.
-      # @api private
+      # @param body [String, Hash, Array, nil] El cuerpo original.
+      # @return [Object] El cuerpo parseado o el original si falla.
       def parse_body(body)
-        return nil if body.nil? || body.empty?
+        return nil if body.nil? || (body.respond_to?(:empty?) && body.empty?)
 
-        # Si ya es un objeto (ej: tests o mocks), lo dejamos pasar, si es String intentamos parsear.
-        parsed = body.is_a?(String) ? JSON.parse(body) : body
+        # Si ya es un objeto (ej: mocks), lo dejamos pasar; si es String, parseamos.
+        parsed = body.is_a?(String) ? safe_json_parse(body) : body
 
         # Rails Magic: Indifferent Access
-        # Si estamos en un entorno Rails, aplicamos la conversión para UX del desarrollador.
-        if defined?(ActiveSupport)
-          if parsed.is_a?(Array)
-            parsed.map! { |e| e.try(:with_indifferent_access) || e }
-          elsif parsed.is_a?(Hash)
-            parsed = parsed.with_indifferent_access
-          end
-        end
+        apply_indifferent_access(parsed)
+      end
 
-        parsed
+      # Parsea JSON de forma segura, retornando el original si falla.
+      def safe_json_parse(json_string)
+        JSON.parse(json_string)
       rescue JSON::ParserError
-        # Si el body no es un JSON válido (ej: texto plano o error del servidor),
-        # devolvemos el string original sin lanzar excepción.
-        body
+        json_string
+      end
+
+      # Aplica ActiveSupport::HashWithIndifferentAccess si es posible.
+      def apply_indifferent_access(data)
+        return data unless defined?(ActiveSupport)
+
+        if data.is_a?(Array)
+          data.map! { |e| e.try(:with_indifferent_access) || e }
+        elsif data.is_a?(Hash)
+          data.with_indifferent_access
+        else
+          data
+        end
       end
     end
   end

data/lib/bug_bunny/middleware/raise_error.rb

@@ -1,61 +1,30 @@
 # lib/bug_bunny/middleware/raise_error.rb
+# frozen_string_literal: true
+
+require_relative '../middleware'
+
 module BugBunny
   module Middleware
     # Middleware que inspecciona el status de la respuesta y lanza excepciones
     # si se encuentran errores (4xx o 5xx).
     #
-    # Mapea los códigos de estado HTTP/AMQP a excepciones específicas de Ruby para facilitar
-    # el manejo de errores mediante `rescue`.
-    #
-    # @note Orden de Middlewares:
-    #   Se recomienda usar este middleware **antes** de `JsonResponse` si deseas que
-    #   la excepción contenga el cuerpo ya parseado (Hash).
-    #
-    # @example Configuración recomendada
-    #   client = BugBunny::Client.new(pool: POOL) do |conn|
-    #     conn.use BugBunny::Middleware::RaiseError   # 1. Verifica errores primero (al salir)
-    #     conn.use BugBunny::Middleware::JsonResponse # 2. Parsea JSON
-    #   end
-    class RaiseError
-      # Inicializa el middleware.
-      # @param app [Object] El siguiente middleware o la aplicación final.
-      def initialize(app)
-        @app = app
-      end
-
-      # Ejecuta el middleware.
-      # Realiza la petición y, al retornar, verifica el estado de la respuesta.
+    # @see BugBunny::Middleware
+    class RaiseError < BugBunny::Middleware
+      # Hook de ciclo de vida: Ejecutado después de recibir la respuesta.
       #
-      # @param env [BugBunny::Request] El objeto request actual.
-      # @return [Hash] La respuesta si el status es exitoso (2xx).
-      # @raise [BugBunny::ClientError] Si el status es 4xx.
-      # @raise [BugBunny::ServerError] Si el status es 5xx.
-      def call(env)
-        response = @app.call(env)
-        on_complete(response)
-        response
-      end
-
       # Verifica el código de estado y lanza la excepción correspondiente.
       #
-      # Mapeo de errores:
-      # * 400 -> {BugBunny::BadRequest}
-      # * 404 -> {BugBunny::NotFound}
-      # * 406 -> {BugBunny::NotAcceptable}
-      # * 408 -> {BugBunny::RequestTimeout}
-      # * 422 -> {BugBunny::UnprocessableEntity}
-      # * 500 -> {BugBunny::InternalServerError}
-      # * Otros 4xx -> {BugBunny::ClientError}
-      #
       # @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.
       # @return [void]
       def on_complete(response)
         status = response['status'].to_i
-        body = response['body'] # Nota: Puede ser String o Hash dependiendo de JsonResponse
+        body = response['body']
 
         case status
         when 200..299
-          # OK: No action needed
+          nil # OK
         when 400 then raise BugBunny::BadRequest, body
         when 404 then raise BugBunny::NotFound
         when 406 then raise BugBunny::NotAcceptable
@@ -63,9 +32,18 @@ module BugBunny
         when 422 then raise BugBunny::UnprocessableEntity, body
         when 500 then raise BugBunny::InternalServerError, body
         else
-          raise BugBunny::ClientError, "Unknown error: #{status}" if status >= 400
+          handle_unknown_error(status)
         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
+      end
     end
   end
 end

data/lib/bug_bunny/middleware.rb

@@ -0,0 +1,44 @@
+# lib/bug_bunny/middleware.rb
+# frozen_string_literal: true
+
+module BugBunny
+  # Clase base para todos los middlewares de BugBunny.
+  #
+  # Implementa el patrón "Template Method" para estandarizar el flujo de ejecución
+  # de la cadena de responsabilidades (Ida y Vuelta).
+  #
+  # Las subclases deben implementar:
+  # * {#on_request} para modificar la petición antes de enviarla.
+  # * {#on_complete} para modificar la respuesta después de recibirla.
+  #
+  # @abstract Subclase y anula {#on_request} o {#on_complete} para inyectar lógica.
+  class Middleware
+    # @return [Object] El siguiente middleware en la pila o el adaptador final.
+    attr_reader :app
+
+    # Inicializa el middleware.
+    #
+    # @param app [Object] El siguiente eslabón de la cadena.
+    def initialize(app)
+      @app = app
+    end
+
+    # Ejecuta el middleware orquestando los hooks de ciclo de vida.
+    #
+    # 1. Llama a {#on_request} (Ida).
+    # 2. Llama al siguiente eslabón (`@app.call`).
+    # 3. Llama a {#on_complete} (Vuelta).
+    #
+    # @param env [BugBunny::Request] El objeto request (entorno).
+    # @return [Hash] La respuesta final procesada.
+    def call(env)
+      on_request(env) if respond_to?(:on_request)
+
+      response = @app.call(env)
+
+      on_complete(response) if respond_to?(:on_complete)
+
+      response
+    end
+  end
+end

data/lib/bug_bunny/version.rb

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

data/lib/bug_bunny.rb

@@ -13,6 +13,7 @@ require_relative 'bug_bunny/resource'
 require_relative 'bug_bunny/rabbit'
 require_relative 'bug_bunny/consumer'
 require_relative 'bug_bunny/controller'
+require_relative 'bug_bunny/middleware'
 
 require_relative 'bug_bunny/middleware/stack'
 require_relative 'bug_bunny/middleware/raise_error'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bug_bunny
 version: !ruby/object:Gem::Version
-  version: 3.0.3
+  version: 3.0.4
 platform: ruby
 authors:
 - gabix
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-02-13 00:00:00.000000000 Z
+date: 2026-02-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bunny
@@ -200,6 +200,7 @@ files:
 - lib/bug_bunny/consumer.rb
 - lib/bug_bunny/controller.rb
 - lib/bug_bunny/exception.rb
+- lib/bug_bunny/middleware.rb
 - lib/bug_bunny/middleware/json_response.rb
 - lib/bug_bunny/middleware/raise_error.rb
 - lib/bug_bunny/middleware/stack.rb