Class: BugBunny::Configuration

Inherits:
Object
  • Object
show all
Defined in:
lib/bug_bunny/configuration.rb

Overview

Clase de configuración global para la gema BugBunny. Almacena las credenciales de conexión, timeouts y parámetros de ajuste de RabbitMQ, así como las opciones por defecto para la declaración de infraestructura AMQP.

Examples:

Configuración en un inicializador (e.g., config/initializers/bug_bunny.rb)

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

Constant Summary collapse

VALIDATIONS =

Reglas de validación por atributo. Solo cubre los atributos de conexión y timeout — los demás (logger, procs, hashes) son tipos arbitrarios que no tienen sentido validar de forma genérica.

Claves soportadas:

  • ‘:type` — clase que debe responder `is_a?`

  • ‘:required` — si `true`, nil o string vacío lanzan ConfigurationError

  • ‘:range` — rango válido de valores (solo para Integer)

{
  host: { type: String, required: true },
  port: { type: Integer, required: true, range: 1..65_535 },
  username: { type: String, required: true },
  password: { type: String, required: true },
  vhost: { type: String, required: true },
  heartbeat: { type: Integer, range: 0..3_600 },
  connection_timeout: { type: Integer, range: 1..300 },
  read_timeout: { type: Integer, range: 1..300 },
  write_timeout: { type: Integer, range: 1..300 },
  rpc_timeout: { type: Integer, range: 1..3_600 },
  channel_prefetch: { type: Integer, range: 1..10_000 }
}.freeze

Configuración de Infraestructura Global collapse

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Configuration

Inicializa la configuración con valores por defecto seguros.



168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
 
# File 'lib/bug_bunny/configuration.rb', line 168

def initialize
  @host = '127.0.0.1'
  @port = 5672
  @username = 'guest'
  @password = 'guest'
  @vhost = '/'

  @logger = Logger.new($stdout)
  @logger.level = Logger::INFO

  @bunny_logger = Logger.new($stdout)
  @bunny_logger.level = Logger::WARN
  @automatically_recover = true
  @network_recovery_interval = 5
  @max_reconnect_attempts = nil
  @max_reconnect_interval = 60
  @connection_timeout = 10
  @read_timeout = 30
  @write_timeout = 30
  @heartbeat = 15
  @continuation_timeout = 15_000
  @channel_prefetch = 1
  @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 = 'BugBunny::Controllers'

  @log_tags = [:uuid]

  # Inicialización de opciones de infraestructura como hashes vacíos para permitir fusiones posteriores.
  @exchange_options = {}
  @queue_options = {}

  @consumer_middlewares = ConsumerMiddleware::Stack.new
  init_callback_defaults
end

Instance Attribute Details

#automatically_recover ⇒ Boolean

Returns Si ‘true`, Bunny intentará reconectar automáticamente.

Returns:

  • (Boolean) —

    Si ‘true`, Bunny intentará reconectar automáticamente.



61
62
63
 
# File 'lib/bug_bunny/configuration.rb', line 61

def automatically_recover
  @automatically_recover
end

#bunny_logger ⇒ Logger

Returns Logger específico para el driver Bunny.

Returns:

  • (Logger) —

    Logger específico para el driver Bunny.



58
59
60
 
# File 'lib/bug_bunny/configuration.rb', line 58

def bunny_logger
  @bunny_logger
end

#channel_prefetch ⇒ Integer

Returns Cantidad de mensajes que el consumidor pre-cargará (QoS).

Returns:

  • (Integer) —

    Cantidad de mensajes que el consumidor pre-cargará (QoS).



89
90
91
 
# File 'lib/bug_bunny/configuration.rb', line 89

def channel_prefetch
  @channel_prefetch
end

#connection_timeout ⇒ Integer

Returns Timeout en segundos para establecer la conexión TCP inicial.

Returns:

  • (Integer) —

    Timeout en segundos para establecer la conexión TCP inicial.



74
75
76
 
# File 'lib/bug_bunny/configuration.rb', line 74

def connection_timeout
  @connection_timeout
end

#consumer_middlewares ⇒ BugBunny::ConsumerMiddleware::Stack (readonly)

Returns Stack de middlewares ejecutados antes de procesar cada mensaje. Los middlewares se registran con BugBunny::ConsumerMiddleware::Stack#use.

Returns:



123
124
125
 
# File 'lib/bug_bunny/configuration.rb', line 123

def consumer_middlewares
  @consumer_middlewares
end

#continuation_timeout ⇒ Integer

Returns Timeout en milisegundos para operaciones de continuación RPC internas.

Returns:

  • (Integer) —

    Timeout en milisegundos para operaciones de continuación RPC internas.



86
87
88
 
# File 'lib/bug_bunny/configuration.rb', line 86

def continuation_timeout
  @continuation_timeout
end

#controller_namespace ⇒ String

Returns Namespace base donde se buscarán los controladores (default: ‘Rabbit::Controllers’).

Returns:

  • (String) —

    Namespace base donde se buscarán los controladores (default: ‘Rabbit::Controllers’).



104
105
106
 
# File 'lib/bug_bunny/configuration.rb', line 104

def controller_namespace
  @controller_namespace
end

#exchange_options ⇒ Hash

Returns Opciones globales por defecto para la declaración de Exchanges. Estas opciones se fusionarán con los valores por defecto de la gema y las específicas del recurso. @example { durable: true, auto_delete: false }.

Returns:

  • (Hash) —

    Opciones globales por defecto para la declaración de Exchanges. Estas opciones se fusionarán con los valores por defecto de la gema y las específicas del recurso. @example { durable: true, auto_delete: false }



114
115
116
 
# File 'lib/bug_bunny/configuration.rb', line 114

def exchange_options
  @exchange_options
end

#health_check_file ⇒ String?

Returns 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’.

Returns:

  • (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’



101
102
103
 
# File 'lib/bug_bunny/configuration.rb', line 101

def health_check_file
  @health_check_file
end

#health_check_interval ⇒ Integer

Returns Intervalo en segundos para verificar la salud de la cola.

Returns:

  • (Integer) —

    Intervalo en segundos para verificar la salud de la cola.



95
96
97
 
# File 'lib/bug_bunny/configuration.rb', line 95

def health_check_interval
  @health_check_interval
end

#heartbeat ⇒ Integer

Returns Intervalo en segundos para enviar latidos (heartbeats).

Returns:

  • (Integer) —

    Intervalo en segundos para enviar latidos (heartbeats).



83
84
85
 
# File 'lib/bug_bunny/configuration.rb', line 83

def heartbeat
  @heartbeat
end

#host ⇒ String

Returns Host o IP del servidor RabbitMQ (ej: ‘localhost’).

Returns:

  • (String) —

    Host o IP del servidor RabbitMQ (ej: ‘localhost’).



40
41
42
 
# File 'lib/bug_bunny/configuration.rb', line 40

def host
  @host
end

#log_tags ⇒ Array<Symbol, Proc, String>

Returns Etiquetas para el log estructurado.

Returns:

  • (Array<Symbol, Proc, String>) —

    Etiquetas para el log estructurado.



107
108
109
 
# File 'lib/bug_bunny/configuration.rb', line 107

def log_tags
  @log_tags
end

#logger ⇒ Logger

Returns Instancia del logger para depuración (default: Logger a STDOUT).

Returns:

  • (Logger) —

    Instancia del logger para depuración (default: Logger a STDOUT).



55
56
57
 
# File 'lib/bug_bunny/configuration.rb', line 55

def logger
  @logger
end

#max_reconnect_attempts ⇒ Integer?

Returns Número máximo de intentos de reconexión del Consumer antes de rendirse. Si es ‘nil` (default), reintenta indefinidamente.

Returns:

  • (Integer, nil) —

    Número máximo de intentos de reconexión del Consumer antes de rendirse. Si es ‘nil` (default), reintenta indefinidamente.



68
69
70
 
# File 'lib/bug_bunny/configuration.rb', line 68

def max_reconnect_attempts
  @max_reconnect_attempts
end

#max_reconnect_interval ⇒ Integer

Returns Techo en segundos para el backoff exponencial de reconexión (default: 60).

Returns:

  • (Integer) —

    Techo en segundos para el backoff exponencial de reconexión (default: 60).



71
72
73
 
# File 'lib/bug_bunny/configuration.rb', line 71

def max_reconnect_interval
  @max_reconnect_interval
end

#nack_raise ⇒ Boolean

Returns Si ‘true` (default), Producer#confirmed levanta PublishNacked cuando el broker NACKea la publicación. Si `false`, el NACK solo se logea como `producer.confirms_nacked` y la llamada retorna `{ ’status’ => 202 }‘ (modo legacy).

El valor puede sobreescribirse por request pasando ‘nack_raise:` en `Client#publish`.

Returns:

  • (Boolean) —

    Si ‘true` (default), Producer#confirmed levanta PublishNacked cuando el broker NACKea la publicación. Si `false`, el NACK solo se logea como `producer.confirms_nacked` y la llamada retorna `{ ’status’ => 202 }‘ (modo legacy).

    El valor puede sobreescribirse por request pasando ‘nack_raise:` en `Client#publish`.



163
164
165
 
# File 'lib/bug_bunny/configuration.rb', line 163

def nack_raise
  @nack_raise
end

#network_recovery_interval ⇒ Integer

Returns Tiempo en segundos a esperar antes de intentar reconectar (base del backoff).

Returns:

  • (Integer) —

    Tiempo en segundos a esperar antes de intentar reconectar (base del backoff).



64
65
66
 
# File 'lib/bug_bunny/configuration.rb', line 64

def network_recovery_interval
  @network_recovery_interval
end

#on_return ⇒ Proc?

Returns Callback invocado cuando el broker retorna un mensaje publicado con ‘mandatory: true` que no pudo ser ruteado a ninguna cola. Si es `nil`, BugBunny logea el evento como `session.broker_return` con nivel `:warn` por default.

Firma: ‘->(return_info, properties, body) { … }` donde:

  • ‘return_info` es `Bunny::ReturnInfo` (reply_code, reply_text, exchange, routing_key)

  • ‘properties` es `Bunny::MessageProperties`

  • ‘body` es el payload crudo como `String`

El callback se ejecuta en el hilo del consumidor interno de Bunny — debe ser rápido y no lanzar excepciones (BugBunny las captura, pero degradan visibilidad).

@example

config.on_return = ->(ri, _props, body) {
  MyAlerts.publish_unroutable(rk: ri.routing_key, body: body)
}.

Returns:

  • (Proc, nil) —

    Callback invocado cuando el broker retorna un mensaje publicado con ‘mandatory: true` que no pudo ser ruteado a ninguna cola. Si es `nil`, BugBunny logea el evento como `session.broker_return` con nivel `:warn` por default.

    Firma: ‘->(return_info, properties, body) { … }` donde:

    • ‘return_info` es `Bunny::ReturnInfo` (reply_code, reply_text, exchange, routing_key)

    • ‘properties` es `Bunny::MessageProperties`

    • ‘body` es el payload crudo como `String`

    El callback se ejecuta en el hilo del consumidor interno de Bunny — debe ser rápido y no lanzar excepciones (BugBunny las captura, pero degradan visibilidad).

    @example

    config.on_return = ->(ri, _props, body) {
  MyAlerts.publish_unroutable(rk: ri.routing_key, body: body)
}



154
155
156
 
# File 'lib/bug_bunny/configuration.rb', line 154

def on_return
  @on_return
end

#on_rpc_reply ⇒ Proc?

Returns Callback invocado en el thread llamante tras recibir el reply RPC, con los headers AMQP de la respuesta. Permite hidratar trace context en el publisher. @example

config.on_rpc_reply = ->(headers) { ExisRay::Tracer.hydrate(headers['X-Amzn-Trace-Id']) }.

Returns:

  • (Proc, nil) —

    Callback invocado en el thread llamante tras recibir el reply RPC, con los headers AMQP de la respuesta. Permite hidratar trace context en el publisher. @example

    config.on_rpc_reply = ->(headers) { ExisRay::Tracer.hydrate(headers['X-Amzn-Trace-Id']) }



136
137
138
 
# File 'lib/bug_bunny/configuration.rb', line 136

def on_rpc_reply
  @on_rpc_reply
end

#password ⇒ String

Returns Contraseña para la autenticación (default: ‘guest’).

Returns:

  • (String) —

    Contraseña para la autenticación (default: ‘guest’).



49
50
51
 
# File 'lib/bug_bunny/configuration.rb', line 49

def password
  @password
end

#port ⇒ Integer

Returns Puerto del servidor RabbitMQ (default: 5672).

Returns:

  • (Integer) —

    Puerto del servidor RabbitMQ (default: 5672).



43
44
45
 
# File 'lib/bug_bunny/configuration.rb', line 43

def port
  @port
end

#queue_options ⇒ Hash

Returns Opciones globales por defecto para la declaración de Colas. Estas opciones se fusionarán con los valores por defecto de la gema y las específicas del recurso. @example { durable: true, exclusive: false }.

Returns:

  • (Hash) —

    Opciones globales por defecto para la declaración de Colas. Estas opciones se fusionarán con los valores por defecto de la gema y las específicas del recurso. @example { durable: true, exclusive: false }



119
120
121
 
# File 'lib/bug_bunny/configuration.rb', line 119

def queue_options
  @queue_options
end

#read_timeout ⇒ Integer

Returns Timeout en segundos para leer datos del socket TCP.

Returns:

  • (Integer) —

    Timeout en segundos para leer datos del socket TCP.



77
78
79
 
# File 'lib/bug_bunny/configuration.rb', line 77

def read_timeout
  @read_timeout
end

#rpc_reply_headers ⇒ Proc?

Returns Callback invocado justo antes del ‘basic_publish` del reply RPC. Debe retornar un Hash de headers AMQP a inyectar en la respuesta. Ideal para propagar trace context (ej: X-Amzn-Trace-Id) generado por el consumer. @example

config.rpc_reply_headers = -> { { 'X-Amzn-Trace-Id' => ExisRay::Tracer.generate_trace_header } }.

Returns:

  • (Proc, nil) —

    Callback invocado justo antes del ‘basic_publish` del reply RPC. Debe retornar un Hash de headers AMQP a inyectar en la respuesta. Ideal para propagar trace context (ej: X-Amzn-Trace-Id) generado por el consumer. @example

    config.rpc_reply_headers = -> { { 'X-Amzn-Trace-Id' => ExisRay::Tracer.generate_trace_header } }



130
131
132
 
# File 'lib/bug_bunny/configuration.rb', line 130

def rpc_reply_headers
  @rpc_reply_headers
end

#rpc_timeout ⇒ Integer

Returns Tiempo máximo en segundos que el cliente esperará una respuesta RPC.

Returns:

  • (Integer) —

    Tiempo máximo en segundos que el cliente esperará una respuesta RPC.



92
93
94
 
# File 'lib/bug_bunny/configuration.rb', line 92

def rpc_timeout
  @rpc_timeout
end

#username ⇒ String

Returns Usuario para la autenticación (default: ‘guest’).

Returns:

  • (String) —

    Usuario para la autenticación (default: ‘guest’).



46
47
48
 
# File 'lib/bug_bunny/configuration.rb', line 46

def username
  @username
end

#vhost ⇒ String

Returns Virtual Host de RabbitMQ a utilizar (default: ‘/’).

Returns:

  • (String) —

    Virtual Host de RabbitMQ a utilizar (default: ‘/’).



52
53
54
 
# File 'lib/bug_bunny/configuration.rb', line 52

def vhost
  @vhost
end

#write_timeout ⇒ Integer

Returns Timeout en segundos para escribir datos en el socket TCP.

Returns:

  • (Integer) —

    Timeout en segundos para escribir datos en el socket TCP.



80
81
82
 
# File 'lib/bug_bunny/configuration.rb', line 80

def write_timeout
  @write_timeout
end

Instance Method Details

#url ⇒ String

Construye la URL de conexión AMQP basada en los atributos configurados.

Returns:

  • (String) —

    URL formateada amqp://user:pass@host:port/vhost



211
212
213
 
# File 'lib/bug_bunny/configuration.rb', line 211

def url
  "amqp://#{username}:#{password}@#{host}:#{port}/#{vhost}"
end

#validate! ⇒ void

This method returns an undefined value.

Valida todos los atributos definidos en VALIDATIONS. Se invoca automáticamente al final de BugBunny.configure.

Raises:



220
221
222
223
224
225
226
227
228
229
 
# File 'lib/bug_bunny/configuration.rb', line 220

def validate!
  VALIDATIONS.each do |attr, rules|
    value = send(attr)
    validate_required!(attr, value, rules)
    next if value.nil?

    validate_type!(attr, value, rules)
    validate_range!(attr, value, rules)
  end
end