bug_bunny 2.0.2 → 3.0.0

data/lib/bug_bunny/middleware/json_response.rb

@@ -0,0 +1,74 @@
+# lib/bug_bunny/middleware/json_response.rb
+require 'json'
+
+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.
+    #
+    # @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.
+      #
+      # 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.
+      #
+      # @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)
+        response['body'] = parse_body(response['body'])
+        response
+      end
+
+      # 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
+      def parse_body(body)
+        return nil if body.nil? || 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
+
+        # 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
+
+        parsed
+      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
+      end
+    end
+  end
+end

data/lib/bug_bunny/middleware/raise_error.rb

@@ -0,0 +1,71 @@
+# lib/bug_bunny/middleware/raise_error.rb
+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.
+      #
+      # @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'.
+      # @return [void]
+      def on_complete(response)
+        status = response['status'].to_i
+        body = response['body'] # Nota: Puede ser String o Hash dependiendo de JsonResponse
+
+        case status
+        when 200..299
+          # OK: No action needed
+        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
+        else
+          raise BugBunny::ClientError, "Unknown error: #{status}" if status >= 400
+        end
+      end
+    end
+  end
+end

data/lib/bug_bunny/middleware/stack.rb

@@ -0,0 +1,50 @@
+# lib/bug_bunny/middleware/stack.rb
+
+module BugBunny
+  module Middleware
+    # Gestiona una pila (stack) de middlewares para procesar peticiones y respuestas.
+    #
+    # Implementa el patrón "Builder" para construir una cadena de responsabilidades.
+    # Permite registrar clases de middleware que envolverán la ejecución final (el Producer).
+    # Es similar en funcionamiento a `Rack::Builder` o `Faraday::RackBuilder`.
+    #
+    # @example Construcción manual
+    #   stack = BugBunny::Middleware::Stack.new
+    #   stack.use BugBunny::Middleware::Logger
+    #   stack.use BugBunny::Middleware::JsonResponse
+    #
+    #   # 'app' será el Logger, que llama a JsonResponse, que llama a final_producer
+    #   app = stack.build(final_producer)
+    #   app.call(request)
+    class Stack
+      # Inicializa una nueva pila de middlewares vacía.
+      def initialize
+        @middlewares = []
+      end
+
+      # Registra un middleware en la pila.
+      #
+      # @param klass [Class] La clase del middleware. Debe tener un constructor `initialize(app, *args)` y un método `call(env)`.
+      # @param args [Array] Argumentos opcionales que se pasarán al constructor del middleware.
+      # @yield [block] Bloque opcional que se pasará al constructor del middleware.
+      # @return [Array] La lista actualizada de configuraciones de middleware.
+      def use(klass, *args, &block)
+        @middlewares << { klass: klass, args: args, block: block }
+      end
+
+      # Construye la cadena de ejecución (app) componiendo todos los middlewares registrados.
+      #
+      # Itera sobre los middlewares en orden inverso, envolviendo la `final_app` capa por capa.
+      # Esto asegura que el primer middleware agregado con {#use} sea el más externo y, por tanto,
+      # el primero en recibir la llamada `call`.
+      #
+      # @param final_app [Proc, Object] El objeto final que recibirá la petición (generalmente el Producer). Debe responder a `call`.
+      # @return [Object] El primer eslabón de la cadena (el middleware más externo).
+      def build(final_app)
+        @middlewares.reverse.inject(final_app) do |app, config|
+          config[:klass].new(app, *config[:args], &config[:block])
+        end
+      end
+    end
+  end
+end

data/lib/bug_bunny/producer.rb

@@ -0,0 +1,130 @@
+require 'concurrent'
+require 'json'
+require 'securerandom'
+
+module BugBunny
+  # Clase de bajo nivel encargada de la publicación de mensajes en RabbitMQ.
+  #
+  # Actúa como el "motor" de envío del framework. Es responsable de:
+  # 1. Serializar el payload del mensaje.
+  # 2. Manejar la publicación asíncrona (Fire-and-Forget).
+  # 3. Implementar el patrón RPC síncrono utilizando futuros (`Concurrent::IVar`).
+  # 4. Gestionar la escucha de respuestas en la cola especial de RabbitMQ.
+  class Producer
+    # Inicializa el productor.
+    #
+    # Prepara las estructuras de concurrencia necesarias para manejar múltiples
+    # peticiones RPC simultáneas sobre la misma conexión.
+    #
+    # @param session [BugBunny::Session] Sesión activa de Bunny (wrapper).
+    def initialize(session)
+      @session = session
+      # Mapa thread-safe para correlacionar IDs de petición con sus futuros (IVars)
+      @pending_requests = Concurrent::Map.new
+      @reply_listener_mutex = Mutex.new
+      @reply_listener_started = false
+    end
+
+    # Envía un mensaje de forma asíncrona (Fire-and-Forget).
+    #
+    # Serializa el cuerpo del request, resuelve el exchange y publica el mensaje
+    # sin esperar confirmación ni respuesta del consumidor.
+    #
+    # @param request [BugBunny::Request] Objeto con la configuración del envío (body, routing_key, etc).
+    # @return [void]
+    def fire(request)
+      x = @session.exchange(name: request.exchange, type: request.exchange_type)
+      payload = serialize_message(request.body)
+      opts = request.amqp_options
+
+      BugBunny.configuration.logger.info("[BugBunny] Publishing to #{request.exchange}/#{request.final_routing_key}")
+
+      x.publish(payload, opts.merge(routing_key: request.final_routing_key))
+    end
+
+    # Envía un mensaje y bloquea el hilo actual esperando una respuesta (RPC).
+    #
+    # Implementa el mecanismo "Direct Reply-to" de RabbitMQ (`amq.rabbitmq.reply-to`)
+    # para recibir la respuesta directamente sin necesidad de crear colas temporales
+    # por cada petición, lo cual mejora significativamente el rendimiento.
+    #
+    # El flujo es:
+    # 1. Asegura que hay un consumidor escuchando en `amq.rabbitmq.reply-to`.
+    # 2. Genera un `correlation_id` único.
+    # 3. Crea una promesa (`Concurrent::IVar`) y la registra.
+    # 4. Publica el mensaje y bloquea esperando que la promesa se resuelva.
+    #
+    # @param request [BugBunny::Request] Objeto request configurado.
+    # @return [Hash] El cuerpo de la respuesta parseado desde JSON.
+    # @raise [BugBunny::RequestTimeout] Si el servidor no responde dentro del tiempo límite.
+    # @raise [BugBunny::InternalServerError] Si la respuesta no es un JSON válido.
+    def rpc(request)
+      ensure_reply_listener!
+
+      request.correlation_id ||= SecureRandom.uuid
+      request.reply_to = 'amq.rabbitmq.reply-to'
+      wait_timeout = request.timeout || BugBunny.configuration.rpc_timeout
+
+      # Creamos un futuro (IVar) que actuará como semáforo
+      future = Concurrent::IVar.new
+      @pending_requests[request.correlation_id] = future
+
+      begin
+        fire(request)
+
+        # Bloqueamos el hilo aquí hasta que llegue la respuesta o expire el timeout
+        response_payload = future.value(wait_timeout)
+
+        if response_payload.nil?
+          raise BugBunny::RequestTimeout, "Timeout waiting for RPC: #{request.action}"
+        end
+
+        parse_response(response_payload)
+      ensure
+        # Limpieza vital para evitar fugas de memoria en el mapa
+        @pending_requests.delete(request.correlation_id)
+      end
+    end
+
+    private
+
+    # Serializa el mensaje para su transporte.
+    # @param msg [Hash, String, Object] El mensaje a serializar.
+    # @return [String] Cadena JSON o string crudo.
+    def serialize_message(msg)
+      msg.is_a?(Hash) ? msg.to_json : msg.to_s
+    end
+
+    # Intenta parsear la respuesta recibida.
+    # @raise [BugBunny::InternalServerError] Si el payload no es JSON válido.
+    def parse_response(payload)
+      JSON.parse(payload)
+    rescue JSON::ParserError
+      raise BugBunny::InternalServerError, "Invalid JSON response"
+    end
+
+    # Inicia el consumidor de respuestas RPC de forma perezosa (Lazy Initialization).
+    #
+    # Utiliza un patrón de "Double-Checked Locking" con Mutex para asegurar que
+    # solo se crea un listener por instancia de Producer, incluso en entornos multi-hilo.
+    #
+    # Escucha en la pseudo-cola `amq.rabbitmq.reply-to`. Cuando llega un mensaje,
+    # busca el `correlation_id` en el mapa de pendientes y completa el futuro (`IVar`),
+    # desbloqueando así al hilo que llamó a {#rpc}.
+    def ensure_reply_listener!
+      return if @reply_listener_started
+
+      @reply_listener_mutex.synchronize do
+        return if @reply_listener_started
+
+        # 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|
+          if (future = @pending_requests[props.correlation_id])
+            future.set(body)
+          end
+        end
+        @reply_listener_started = true
+      end
+    end
+  end
+end