bug_bunny 3.1.3 → 3.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4aab7949b09bfbf861d4a9ff736bc3bef832fdb3c8a302924544783bdbc9e1bf
-  data.tar.gz: 12b73641a812ec4ce72d2a5ad8992a1f2b91c4b0b11ce181aac02fe3a4912751
+  metadata.gz: a96d4e81fd57e9a1a524aa479bbb85d6fe3a99bd654da95014f633d2fb0cb2d2
+  data.tar.gz: cb49f5e1789c1737572fb98b2d21428cf02c129c33e3049de1a0de4f6270a9d3
 SHA512:
-  metadata.gz: 2f4475f1754c1de91be6576d4fabb23d025b1f3735d4d76d3123415e71b907d2bfc307dd8e8f4a921ad5a11b2524cd85a1ee17ea3fb1d42f6e15c62ddef01425
-  data.tar.gz: c3973288d2d394121491ffb3c7fa809b8841c9fdc3fc87486fb807b62b6f948e48298fd9f4b696132c9b86d448dad82bd4cfa909c39384efc2ab1b7729c15f31
+  metadata.gz: ea0ae037590a852734607ad7e46fabff4cfab87aef068a724da42d506fc79ccda376d0db85f0d4ebd1f516ac2aef963fcdd18604a6d808efb3e4e2de0ca32391
+  data.tar.gz: 6930cc1f181bc7d6968cb4fe3ed82f25cb59650522f45c5ad5e6f9328cc33125bc41d197de35f05f16e1126014ea7ada86cb2d6a348e7c4e0b6a4c8e56a61a7a

data/CHANGELOG.md

@@ -1,4 +1,21 @@
 # Changelog
+## [3.1.5] - 2026-02-25
+
+### ✨ New Features & Improvements
+* **Smart Heuristic Router (Namespace Support):** El enrutador interno del consumidor (`Consumer#router_dispatch`) fue reescrito para soportar namespaces profundos y rutas anidadas sin necesidad de configuración manual. Utiliza una heurística basada en Regex para detectar dinámicamente identificadores (Enteros, UUIDs o hashes alfanuméricos largos) dentro de la URL.
+  * Esto permite que rutas complejas como `GET api/v1/ecommerce/orders/a1b2c3d4/cancel` resuelvan automáticamente al controlador `Api::V1::Ecommerce::OrdersController`, asignando `id: a1b2c3d4` y `action: cancel`.
+
+## [3.1.4] - 2026-02-21
+
+### 🚀 Cloud Native & Infrastructure Features
+* **Docker Swarm / Kubernetes Health Checks:** Introduced native support for external orchestrator health checks using the **Touchfile** pattern.
+  * Added `config.health_check_file` to the global configuration.
+  * The `Consumer`'s internal heartbeat now automatically updates the modification time (`touch`) of the specified file upon successful validation of the RabbitMQ connection and queue existence.
+  * Fails gracefully without interrupting the consumer if file system permissions are restricted.
+
+### 📖 Documentation
+* **Production Guide Expansion:** Added a comprehensive "Health Checks en Docker Swarm / Kubernetes" section to the README. Includes detailed `docker-compose.yml` examples demonstrating best practices for integrating the touchfile pattern, specifically highlighting the critical use of `start_period` to accommodate Rails boot times.
+
 ## [3.1.3] - 2026-02-19
 
 ### 🏗️ Architectural Refactoring (Middleware Standardization)

data/README.md

@@ -76,11 +76,14 @@ BugBunny.configure do |config|
   config.rpc_timeout = 10               # Segundos máx para esperar respuesta (Síncrono)
   config.network_recovery_interval = 5  # Reintento de conexión
 
-  # 3. Logging
+  # 3. Health Checks (Opcional, para Docker Swarm / K8s)
+  config.health_check_file = '/tmp/bug_bunny_health'
+
+  # 4. Logging
   config.logger = Rails.logger
 end
 
-# 4. Connection Pool (CRÍTICO para concurrencia)
+# 5. Connection Pool (CRÍTICO para concurrencia)
 # Define un pool global para compartir conexiones entre hilos
 BUG_BUNNY_POOL = ConnectionPool.new(size: ENV.fetch('RAILS_MAX_THREADS', 5).to_i, timeout: 5) do
   BugBunny.create_connection
@@ -377,6 +380,35 @@ Para máxima velocidad, BugBunny usa `amq.rabbitmq.reply-to`.
 ### Seguridad
 El Router incluye protecciones contra **Remote Code Execution (RCE)**. Verifica estrictamente que la clase instanciada herede de `BugBunny::Controller` antes de ejecutarla, impidiendo la inyección de clases arbitrarias de Ruby vía el header `type`.
 
+### Health Checks en Docker Swarm / Kubernetes
+Dado que un Worker se ejecuta en segundo plano sin exponer un servidor web tradicional, orquestadores como Docker Swarm o Kubernetes no pueden usar un endpoint HTTP para verificar si el proceso está saludable.
+
+BugBunny implementa el patrón **Touchfile**. Puedes configurar la gema para que actualice la fecha de modificación de un archivo temporal en cada latido exitoso (heartbeat) hacia RabbitMQ.
+
+**1. Configurar la gema:**
+```ruby
+# config/initializers/bug_bunny.rb
+BugBunny.configure do |config|
+  # Actualizará la fecha de este archivo si la conexión a la cola está sana
+  config.health_check_file = '/tmp/bug_bunny_health'
+end
+```
+
+**2. Configurar el Orquestador (Ejemplo docker-compose.yml):**
+Con esta configuración, Docker Swarm verificará que el archivo haya sido modificado (tocado) en los últimos 15 segundos. Si el worker se bloquea o pierde la conexión de manera irrecuperable, Docker reiniciará el contenedor automáticamente.
+
+```yaml
+services:
+  worker:
+    image: my_rails_app
+    command: bundle exec rake bug_bunny:work
+    healthcheck:
+      test: ["CMD-SHELL", "test $$(expr $$(date +%s) - $$(stat -c %Y /tmp/bug_bunny_health)) -lt 15 || exit 1"]
+      interval: 10s
+      timeout: 5s
+      retries: 3
+```
+
 ---
 
 ## 📄 Licencia

data/lib/bug_bunny/configuration.rb

@@ -11,6 +11,7 @@ module BugBunny
   #   BugBunny.configure do |config|
   #     config.host = '127.0.0.1'
   #     config.exchange_options = { durable: true, auto_delete: false }
+  #     config.health_check_file = '/tmp/bug_bunny_health'
   #   end
   class Configuration
     # @return [String] Host o IP del servidor RabbitMQ (ej: 'localhost').
@@ -64,6 +65,12 @@ module BugBunny
     # @return [Integer] Intervalo en segundos para verificar la salud de la cola.
     attr_accessor :health_check_interval
 
+    # @return [String, nil] Ruta del archivo que se actualizará (touch) en cada health check exitoso.
+    #   Ideal para sondas (probes) de orquestadores como Docker Swarm o Kubernetes.
+    #   Si es `nil`, la funcionalidad de touchfile se desactiva.
+    #   @example '/tmp/bug_bunny_health'
+    attr_accessor :health_check_file
+
     # @return [String] Namespace base donde se buscarán los controladores (default: 'Rabbit::Controllers').
     attr_accessor :controller_namespace
 
@@ -108,6 +115,9 @@ module BugBunny
       @rpc_timeout = 10
       @health_check_interval = 60
 
+      # Desactivado por defecto. El usuario debe especificar una ruta explícita para habilitarlo.
+      @health_check_file = nil
+
       # Configuración por defecto para mantener compatibilidad
       @controller_namespace = 'Rabbit::Controllers'
 

data/lib/bug_bunny/consumer.rb

@@ -1,10 +1,12 @@
-# lib/bug_bunny/consumer.rb
+# frozen_string_literal: true
+
 require 'active_support/core_ext/string/inflections'
 require 'concurrent'
 require 'json'
 require 'uri'
 require 'cgi'
 require 'rack/utils' # Necesario para parse_nested_query
+require 'fileutils'  # Necesario para el touchfile del health check
 
 module BugBunny
   # Consumidor de mensajes AMQP que actúa como un Router RESTful.
@@ -177,44 +179,58 @@ module BugBunny
 
     # Interpreta la URL y el verbo para decidir qué controlador ejecutar.
     #
-    # Utiliza `Rack::Utils.parse_nested_query` para soportar parámetros anidados
-    # como `q[service]=rabbit`.
+    # Implementa un Router Heurístico que soporta namespaces y acciones custom
+    # buscando dinámicamente el ID en la ruta.
     #
     # @param method [String] Verbo HTTP (GET, POST, etc).
-    # @param path [String] URL virtual del recurso (ej: 'users/1?active=true').
+    # @param path [String] URL virtual del recurso (ej: 'foo/bar/algo/13/test').
     # @return [Hash] Estructura con keys {:controller, :action, :id, :params}.
     def router_dispatch(method, path)
-      # Usamos URI para separar path de query string
       uri = URI.parse("http://dummy/#{path}")
       segments = uri.path.split('/').reject(&:empty?)
 
-      # --- FIX: Uso de Rack para soportar params anidados ---
       query_params = uri.query ? Rack::Utils.parse_nested_query(uri.query) : {}
-
-      # Si estamos en Rails, convertimos a HashWithIndifferentAccess para comodidad
       if defined?(ActiveSupport::HashWithIndifferentAccess)
         query_params = query_params.with_indifferent_access
       end
 
-      # Lógica de Ruteo Convencional
-      controller_name = segments[0]
-      id = segments[1]
-
-      action = case method.to_s.upcase
-               when 'GET' then id ? 'show' : 'index'
-               when 'POST' then 'create'
-               when 'PUT', 'PATCH' then 'update'
-               when 'DELETE' then 'destroy'
-               else id || 'index'
-               end
-
-      # Soporte para rutas miembro custom (POST users/1/promote)
-      if segments.size >= 3
-         id = segments[1]
-         action = segments[2]
+      # 1. Acción Built-in: Health Check Global (/up o /api/up)
+      if segments.last == 'up' && method.to_s.upcase == 'GET'
+        # Si la ruta es solo 'up', usamos un controlador genérico 'application'
+        ctrl = segments.size > 1 ? segments[0...-1].join('/') : 'application'
+        return { controller: ctrl, action: 'up', id: nil, params: query_params }
+      end
+
+      # 2. Búsqueda dinámica del ID (Heurística)
+      # Patrón: Números enteros, UUIDs, o hashes alfanuméricos largos (MongoDB/Snowflake)
+      id_pattern = /^(?:\d+|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[0-9a-fA-F]{24})$/
+      id_index = segments.find_index { |s| s.match?(id_pattern) }
+
+      if id_index
+        # ESCENARIO A: Ruta Miembro (ej. foo/bar/algo/13/test)
+        # Todo lo que está antes del ID es el namespace/controlador
+        controller_name = segments[0...id_index].join('/') # "foo/bar/algo"
+        id = segments[id_index]                            # "13"
+        action = segments[id_index + 1]                    # "test" (puede ser nil)
+      else
+        # ESCENARIO B: Ruta Colección (ej. foo/bar/algo o api/v1/users)
+        controller_name = segments.join('/')
+        id = nil
+        action = nil
       end
 
-      # Inyectamos el ID en los params si existe en la ruta
+      # 3. Inferimos la acción si no hay una explícita en la ruta
+      unless action
+        action = case method.to_s.upcase
+                 when 'GET' then id ? 'show' : 'index'
+                 when 'POST' then 'create'
+                 when 'PUT', 'PATCH' then 'update'
+                 when 'DELETE' then 'destroy'
+                 else id ? 'show' : 'index'
+                 end
+      end
+
+      # 4. Inyectamos el ID en los parámetros para que el Controller lo tenga fácil
       query_params['id'] = id if id
 
       { controller: controller_name, action: action, id: id, params: query_params }
@@ -253,14 +269,40 @@ module BugBunny
     # Tarea de fondo (Heartbeat lógico) para verificar la salud del canal.
     # Si la cola desaparece o la conexión se cierra, fuerza una reconexión.
     #
+    # Adicionalmente, si `health_check_file` está configurado, actualiza la
+    # fecha de modificación (touch) de dicho archivo para notificar a orquestadores
+    # externos (como Docker Swarm o Kubernetes) que el proceso está saludable.
+    #
     # @param q_name [String] Nombre de la cola a monitorear.
+    # @return [void]
     def start_health_check(q_name)
+      file_path = BugBunny.configuration.health_check_file
+
+      # Toque inicial para indicar al orquestador que el worker arrancó correctamente
+      touch_health_file(file_path) if file_path
+
       Concurrent::TimerTask.new(execution_interval: BugBunny.configuration.health_check_interval) do
+        # 1. Verificamos la salud de RabbitMQ (si falla, levanta un error y corta la ejecución del bloque)
         session.channel.queue_declare(q_name, passive: true)
-      rescue StandardError
-        BugBunny.configuration.logger.warn("[BugBunny::Consumer] ⚠️  Queue check failed. Reconnecting session...")
+
+        # 2. Si llegamos aquí, RabbitMQ y la cola están vivos. Avisamos al orquestador actualizando el archivo.
+        touch_health_file(file_path) if file_path
+      rescue StandardError => e
+        BugBunny.configuration.logger.warn("[BugBunny::Consumer] ⚠️  Queue check failed: #{e.message}. Reconnecting session...")
         session.close
       end.execute
     end
+
+    # Actualiza la fecha de modificación del archivo de health check (touchfile).
+    # Se utiliza un `rescue` genérico para no interrumpir el flujo principal del worker
+    # si el contenedor de Docker tiene problemas de permisos sobre la carpeta temporal.
+    #
+    # @param file_path [String] Ruta absoluta del archivo a tocar.
+    # @return [void]
+    def touch_health_file(file_path)
+      FileUtils.touch(file_path)
+    rescue StandardError => e
+      BugBunny.configuration.logger.error("[BugBunny::Consumer] ⚠️  Cannot touch health check file '#{file_path}': #{e.message}")
+    end
   end
 end

data/lib/bug_bunny/producer.rb

@@ -110,7 +110,7 @@ module BugBunny
       BugBunny.configuration.logger.info("[BugBunny::Producer] 📤 #{verb} /#{target} | RK: '#{rk}' | ID: #{id}")
 
       # DEBUG: Detalle completo de Infraestructura y Payload
-      BugBunny.configuration.logger.debug("[BugBunny::Producer] ⚙️  Exchange Opts: #{final_x_opts}")
+      BugBunny.configuration.logger.debug("[BugBunny::Producer] ⚙️ Exchange #{request.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/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bug_bunny
 version: !ruby/object:Gem::Version
-  version: 3.1.3
+  version: 3.1.5
 platform: ruby
 authors:
 - gabix
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-02-19 00:00:00.000000000 Z
+date: 2026-02-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bunny