bug_bunny 3.1.3 → 3.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4aab7949b09bfbf861d4a9ff736bc3bef832fdb3c8a302924544783bdbc9e1bf
-  data.tar.gz: 12b73641a812ec4ce72d2a5ad8992a1f2b91c4b0b11ce181aac02fe3a4912751
+  metadata.gz: 28bb35f1140309e9527c44f108cba3b58b85aae52c7253d17f35f7b35e248661
+  data.tar.gz: f3b30d3b77b1c242c3e8c8fc9576d8143b2587b60da83a0d633604eaca464ebd
 SHA512:
-  metadata.gz: 2f4475f1754c1de91be6576d4fabb23d025b1f3735d4d76d3123415e71b907d2bfc307dd8e8f4a921ad5a11b2524cd85a1ee17ea3fb1d42f6e15c62ddef01425
-  data.tar.gz: c3973288d2d394121491ffb3c7fa809b8841c9fdc3fc87486fb807b62b6f948e48298fd9f4b696132c9b86d448dad82bd4cfa909c39384efc2ab1b7729c15f31
+  metadata.gz: a069a81c26762bedc55cb8c0be70ac6ff2154d70d4b54f10d7650ddc27160cf400c4c8b680e50e0fd3529f39447ccfcb83864ae7d99396ee7ce62ef5d84da6fd
+  data.tar.gz: d8e5130f3d6830023f85516a2dec1db036c49cc0963af8f92255987c32b6e721e2785ed54c4d2b9ac94931c5b3e1073c1b1a549265aabb39839f0b95348deaaa

data/CHANGELOG.md

@@ -1,4 +1,15 @@
 # Changelog
+## [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.
@@ -253,14 +255,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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BugBunny
-  VERSION = "3.1.3"
+  VERSION = "3.1.4"
 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.4
 platform: ruby
 authors:
 - gabix
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-02-19 00:00:00.000000000 Z
+date: 2026-02-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bunny