bug_bunny 5.1.1 → 5.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -5,7 +5,9 @@
5
5
  > `remote_error.rb`, `middleware/raise_error.rb`, `controller.rb`, `consumer.rb`,
6
6
  > `observability.rb` · fecha 2026-07-31 · cobertura: §a/§b/§d completas
7
7
  > (estructura); §c política completa (enrich, **inferida** de HTTP/AMQP —
8
- > verificación humana pendiente).
8
+ > verificación humana pendiente). Incremento 2026-10-16 (#70): las citas de `configuration.rb`
9
+ > (`:293,300,308`, los `raise` de `ConfigurationError`) son del árbol de `67cca83`; el resto sigue
10
+ > anclado a `5697541`.
9
11
 
10
12
  ## 1. Resumen
11
13
 
@@ -46,7 +48,7 @@ Jerarquía (todas bajo `BugBunny::Error < ::StandardError`):
46
48
  |---|---|---|
47
49
  | `Error` | `::StandardError` | base — no se levanta directa salvo `resource.rb:122` (pool ausente) |
48
50
  | `CommunicationError` | `Error` | `bug_bunny.rb:96`, `session.rb:177,285`, `producer.rb:90`, `client.rb:168` — envuelve cualquier `Bunny::Exception` en la frontera del gem; original en `.cause` |
49
- | `ConfigurationError` | `Error` | `configuration.rb:262,269,277` — validación al final de `BugBunny.configure` |
51
+ | `ConfigurationError` | `Error` | `configuration.rb:293,300,308` — validación al final de `BugBunny.configure` |
50
52
  | `PublishNacked` | `Error` | `producer.rb:235` — NACK del broker en modo `:confirmed`. Attrs: `path`, `nacked_count`. Opt-out `nack_raise: false` |
51
53
  | `PublishUnroutable` | `Error` | `producer.rb:325` — `basic.return` con `mandatory: true`. Attrs: `path`, `exchange`, `routing_key`, `reply_code`, `reply_text`, `correlation_id`. Opt-out `return_raise: false` |
52
54
  | `ClientError` | `Error` | `raise_error.rb:170` — 4xx no mapeado explícito |
@@ -85,7 +87,7 @@ operaciones de RFC-003 (`docs/api/`, hoy pendiente — ver §4), no las redefine
85
87
  | Cliente RPC | otro ≥400 | `ClientError` | 4xx no mapeado |
86
88
  | Productor (publish `:confirmed`) | n/a (AMQP) | `PublishNacked` / `PublishUnroutable` | NACK / return del broker — no es status HTTP |
87
89
  | Transporte (frontera gem) | n/a (AMQP) | `CommunicationError` | fallo de red/broker, envuelve `Bunny::Exception` |
88
- | **Worker (dispatch)** | **403** | — (no excepción; responde 403 + reject) | guard anti-RCE: clase enrutada no subclase de `BugBunny::Controller` (`consumer.rb:222-228`) |
90
+ | **Worker (dispatch)** | **403** | — (no excepción; responde 403 + reject) | guard anti-RCE: clase enrutada no subclase de `BugBunny::Controller` (`consumer.rb:375-381`) |
89
91
 
90
92
  ### c. Política por error
91
93
 
@@ -133,7 +135,7 @@ ante una excepción no mapeada por `rescue_from`:
133
135
  ```
134
136
 
135
137
  - El envelope `bug_bunny_exception` lo arma `RemoteError.serialize` (`remote_error.rb:29`);
136
- también lo agrega `Consumer` cuando `status == 500 && exception` (`consumer.rb:325`).
138
+ también lo agrega `Consumer` cuando `status == 500 && exception` (`consumer.rb:478`).
137
139
  Es lo que el cliente reconstruye como `RemoteError` (`raise_error.rb:61-64`).
138
140
  - `render status:, json:` (`controller.rb:242`) deja el shape del body de error de
139
141
  dominio a criterio del worker — la gema no lo impone.
@@ -168,7 +170,7 @@ parsea el body, devuelve `parsed['errors']` por convención o el cuerpo completo
168
170
  ## 3. Inferencias
169
171
 
170
172
  - **Guard anti-RCE = 403, no excepción.** El control de seguridad que valida la
171
- herencia de la clase enrutada vive en `consumer.rb:222-228`: si la clase
173
+ herencia de la clase enrutada vive en `consumer.rb:375-381`: si la clase
172
174
  resuelta no es subclase de `BugBunny::Controller`, el worker loguea
173
175
  `consumer.security_violation`, responde **403 'Forbidden'** (`handle_fatal_error`)
174
176
  y rechaza el mensaje sin requeue — **no levanta una excepción dedicada**. La ex
@@ -5,7 +5,9 @@
5
5
  > a la RFC vigente) · anclado a `5697541`
6
6
  > (`.github/workflows/release.yml`, `*.gemspec`, `lib/bug_bunny/version.rb`,
7
7
  > `CHANGELOG.md`) · fecha 2026-07-31 · cobertura:
8
- > completa (régimen gema: build→publish, §e/f/g n/a).
8
+ > completa (régimen gema: build→publish, §e/f/g n/a). Incremento 2026-10-16 (release 5.3.0):
9
+ > versión actual y los pines de los consumidores (§h), re-medidos; escrito por el agente, sin
10
+ > verificación humana todavía.
9
11
 
10
12
  ## 1. Resumen
11
13
 
@@ -21,9 +23,9 @@ out-of-repo).
21
23
 
22
24
  ### a. Hecho verificable
23
25
 
24
- - **Convención de versión:** SemVer `vX.X.X`. Actual: **5.1.1**.
25
- - **Source of truth:** tag remoto (`v5.1.1`) + **triple mirror**
26
- `lib/bug_bunny/version.rb` (`VERSION = '5.1.1'`) ← `bug_bunny.gemspec:7`
26
+ - **Convención de versión:** SemVer `vX.X.X`. Actual: **5.3.0**.
27
+ - **Source of truth:** tag remoto (`v5.3.0`) + **triple mirror**
28
+ `lib/bug_bunny/version.rb` (`VERSION = '5.3.0'`) ← `bug_bunny.gemspec:7`
27
29
  (`spec.version = BugBunny::VERSION`).
28
30
  - **Changelog canónico:** `CHANGELOG.md` único.
29
31
  - **Patrón de trigger:** `gema-tag` (patrón 1).
@@ -34,7 +36,7 @@ out-of-repo).
34
36
 
35
37
  - **Convención:** SemVer `vX.X.X` (**con `v`** — distinto al servicio).
36
38
  - **Source of truth:** tag remoto canónico (`git tag --sort=-v:refname` →
37
- `v5.1.1`).
39
+ `v5.3.0`).
38
40
  - **Mirror:** `lib/bug_bunny/version.rb` (`VERSION`), leído por
39
41
  `bug_bunny.gemspec:7` (`spec.version = BugBunny::VERSION`).
40
42
  `required_ruby_version >= 2.6.0` (`bug_bunny.gemspec:17`).
@@ -85,9 +87,12 @@ procedimiento per-repo porque no vive acá. Una versión yankeada se anotaría e
85
87
  `>= 5.1.0, < 5.2.0`, así que un minor **no entra** sin editar el `Gemfile`.
86
88
  Consecuencia operativa: un fix publicado como **patch** lo toman con
87
89
  `bundle update bug_bunny`; uno publicado como **minor** requiere tocar el pin
88
- en cada consumidor. Estado hoy: `box_manager_service` y `box_radius_manager`
89
- en `~> 5.1.0`; `box_acs_manager` y `box_cluster_manager` todavía en
90
- `~> 4.19.0` (bumps pendientes). Un cambio de contrato del gem (ej. el
90
+ en cada consumidor. Estado medido el 2026-10-16 (Gemfile y Gemfile.lock del default de cada clon del
91
+ workspace): `box_manager_service` en `~> 5.1.1`; `box_acs_manager`,
92
+ `box_cluster_manager` y `box_radius_manager` en `~> 5.1.0`, los cuatro con 5.1.1 en el lock — o sea que
93
+ **ni 5.2.0 ni 5.3.0 le entran a ninguno** sin tocar el pin. `agent` sigue en `~> 4.11.1`, y el resto de
94
+ los consumidores (`olt_*`, `*_invoice_service`, `notification_sms_service`, `wispro_box_server`,
95
+ `wispro_lan`) en la línea 0.2.x. *(El 2026-09-29 la medición daba lo mismo para los cuatro de 5.x.)* Un cambio de contrato del gem (ej. el
91
96
  behavior-change de `4.18.0` — `Bunny::Exception` → `CommunicationError`, o la
92
97
  eliminación de `BugBunny::SecurityError` en `5.0.0`) obliga a los consumidores
93
98
  a migrar; el `CHANGELOG.md` lo documenta como breaking note. **Orden de
data/docs/test/testing.md CHANGED
@@ -1,16 +1,22 @@
1
1
  # Test — bug_bunny
2
2
 
3
3
  > meta: artefacto test · RFC-013 · generado `arch-structure` (§a-§d) +
4
- > `arch-enrich` (§e-§h) · anclado a `7bf1da7`, `Rakefile`, `bug_bunny.gemspec`,
4
+ > `arch-enrich` (§e-§h) · anclado a `67cca83` (squash de #71 en `main`; antes `35b075a`, y antes `7bf1da7`, que no era ancestro de `main`), `Rakefile`, `bug_bunny.gemspec`,
5
5
  > `spec/spec_helper.rb`, `spec/support/integration_helper.rb`,
6
6
  > `.github/workflows/main.yml`, `CHANGELOG.md` · fecha 2026-07-22 · cobertura:
7
7
  > §a-§d (estructura) + §e-§h (enrich, anclado a specs/CHANGELOG) completas.
8
+ > Incremento 2026-09-28 (#64): conteos, `drain_*_spec` y el gap de aislamiento.
9
+ > Incremento 2026-10-16 (#70): `spec/rails/` (Railtie con Rails de verdad), tarea
10
+ > `spec:rails` y conteos; re-anclado a `67cca83` en el release 5.3.0. Escrito por el agente, sin
11
+ > verificación humana todavía.
8
12
 
9
13
  ## 1. Resumen
10
14
 
11
- Suite principal **RSpec** (`spec/`, 23 specs: 16 unit + 7 integration). Tarea
15
+ Suite principal **RSpec** (`spec/`, 27 specs: 18 unit + 8 integration + 1 rails). Tarea
12
16
  `:test` legacy de **Minitest** (`test/`, 2 archivos) fuera del default y del CI.
13
- CI corre `bundle exec rake` (= `:spec`) en Ruby 3.4.4. Sin coverage tool
17
+ CI corre `bundle exec rake` en Ruby 3.4.4: el default corre `:spec` y `spec:rails`, cada una en
18
+ su proceso. `bundle exec rspec` pelado corre `spec/` sin Rails: `.rspec` excluye `spec/rails/` salvo que se lo pida
19
+ explícitamente (`bundle exec rspec spec/rails` la corre, en su propio proceso). Sin coverage tool
14
20
  configurado.
15
21
 
16
22
  ## 2. Cuerpo
@@ -19,8 +25,9 @@ configurado.
19
25
 
20
26
  | framework | dir | nivel | nº | propósito |
21
27
  |---|---|---|---|---|
22
- | **RSpec** `~> 3.0` | `spec/unit/` | unit | 16 | client/session pool, configuration, consumer, producer, controller, raise_error, remote_error, request, route, observability, otel, resource, middleware, `extra_top_level_params` (hook de params hermanos en `Resource#save`) |
23
- | **RSpec** | `spec/integration/` | integration | 7 | client, consumer_middleware, controller, error_handling, infrastructure, publisher_confirms, resource — **requieren RabbitMQ real** (usan `BugBunny.create_connection` + pool) |
28
+ | **RSpec** `~> 3.0` | `spec/unit/` | unit | 18 | client/session pool, configuration, consumer, `drain_tracker`, producer, controller, raise_error, remote_error, request, route, observability, otel, resource, middleware, `extra_top_level_params` (hook de params hermanos en `Resource#save`), `consumer_rails_executor_outside_rails` (fuera de Rails no se carga el Railtie ni el middleware del executor) |
29
+ | **RSpec** + `railties`/`activerecord`/`sqlite3` | `spec/rails/` | integration con Rails (sin broker) | 1 | `consumer_rails_executor`: una app Rails mínima (`spec/rails/app.rb`, ActiveRecord sobre SQLite en memoria) prueba que cada mensaje corre dentro del executor — el `CurrentAttributes` no pasa al siguiente, la conexión vuelve al pool, el orden frente a un middleware de tracing, el error que escapa (reject + `Rails.error`) y `consumer_rails_executor = false` (en subproceso) |
30
+ | **RSpec** | `spec/integration/` | integration | 8 | client, consumer_middleware, controller, drain, error_handling, infrastructure, publisher_confirms, resource — **requieren RabbitMQ real** (usan `BugBunny.create_connection` + pool) |
24
31
  | **Minitest** `~> 5.0` (+ `mocha`, `minitest-reporters`) | `test/integration/` | integration (legacy) | 2 | `manual_client_test.rb`, `infrastructure_test.rb` — tarea `:test`, **no** en default ni CI |
25
32
 
26
33
  Sin tags declarados (`:slow`/`:js`) en la config de RSpec.
@@ -29,13 +36,16 @@ Sin tags declarados (`:slow`/`:js`) en la config de RSpec.
29
36
 
30
37
  | objetivo | comando | qué corre |
31
38
  |---|---|---|
32
- | default / CI | `bundle exec rake` | tarea `:spec` (toda la suite RSpec) — `Rakefile:` `task default: :spec` |
39
+ | default / CI | `bundle exec rake` | `:spec` (la suite RSpec menos `spec/rails/`) y después `spec:rails`, cada una en su proceso — `Rakefile:` `task default: [:spec, 'spec:rails']` |
40
+ | `spec/` sin Rails | `bundle exec rspec` | todo `spec/` menos `spec/rails/` (lo excluye `.rspec` cuando no se pide `spec/rails` explícitamente) |
33
41
  | solo unit | `bundle exec rake spec:unit` | `spec/unit/**/*_spec.rb` |
34
42
  | solo integration | `bundle exec rake spec:integration` | `spec/integration/**/*_spec.rb` (requiere broker) |
43
+ | Railtie (Rails) | `bundle exec rake spec:rails` | `spec/rails/**/*_spec.rb`, en su propio proceso (Rails se inicializa una vez por proceso); equivale a `bundle exec rspec spec/rails` |
35
44
  | Minitest legacy | `bundle exec rake test` | `test/**/*_test.rb` |
36
45
  | CI | `.github/workflows/main.yml` → `bundle exec rake` | matrix Ruby `3.4.4`, `ruby/setup-ruby@v1` + `bundler-cache`, on push `main` + PR |
37
46
 
38
- > Todas las tareas RSpec corren con `--require spec_helper` (`Rakefile`).
47
+ > Las tareas RSpec corren con `--require spec_helper` (`Rakefile`), salvo `spec:rails`, que
48
+ > carga su propio `spec/rails/rails_helper.rb`.
39
49
 
40
50
  ### c. Fixtures / Factories
41
51
 
@@ -58,9 +68,9 @@ umbral de coverage declarado.
58
68
  ### e. Gaps de cobertura
59
69
 
60
70
  - **Integration specs no corren en CI:** `main.yml` no declara servicio RabbitMQ;
61
- las 7 integration specs **se skipean** vía `rabbitmq_available?`
71
+ las 8 integration specs **se skipean** vía `rabbitmq_available?`
62
72
  (`spec/support/integration_helper.rb:14`, ver `publisher_confirms_spec.rb:10`).
63
- En CI solo se ejercitan las **16 unit specs** → el contrato AMQP real (publish/
73
+ En CI solo se ejercitan las **17 unit specs** → el contrato AMQP real (publish/
64
74
  consume/confirms contra broker) **no se valida en pipeline**, solo localmente
65
75
  con broker. Gap relevante.
66
76
  - **Sin medición de cobertura:** no hay SimpleCov ni umbral → la cobertura no está
@@ -75,9 +85,18 @@ umbral de coverage declarado.
75
85
  | **Errores RFC-020** (status→excepción, materia prima) | `raise_error_spec`, `remote_error_spec`, `communication_error_wrapping_spec`, `error_handling_spec` (integration) | **bien cubierto** (unit) |
76
86
  | **Consumed RFC-018** (Bunny::Exception→`CommunicationError`) | `communication_error_wrapping_spec`, `client_session_pool_spec` | cubierto (unit) |
77
87
  | **Config RFC-012** (validaciones de `Configuration`) | `configuration_spec` | cubierto |
88
+ | **Consumer#drain** (drenar y salir, #64) | `drain_tracker_spec` (unit, reloj inyectado), `drain_spec` (integration) | cubierto; la parte integration skipea sin broker. Validado por mutación: quitar la espera, el retorno temprano o el chequeo de `busy?` hace fallar el test correspondiente |
78
89
  | **Confirms** (`PublishNacked`/`PublishUnroutable`) | `producer_spec`, `publisher_confirms_spec` (integration) | parcial en CI (la parte integration skipea sin broker) |
79
90
  | **Operaciones/routing** (RFC-003, capa F2) | `route_spec`, `request_spec`, `controller_spec`, `controller_after_action_spec`, `resource_spec` | cubierto (unit) |
80
91
 
92
+ - **Aislamiento entre specs — corregido 2026-09-28 (#64):** el `after` de
93
+ `configuration_spec` reemplazaba la configuración global por una con defaults
94
+ (`guest`), así que los specs de integración que corrían después se conectaban
95
+ como `guest` y se **skipeaban como "RabbitMQ no disponible" aun con broker**.
96
+ Cuántos, dependía del seed (11 en `main` con `--seed 1`). Ahora un `around`
97
+ restaura la configuración original (`spec/unit/configuration_spec.rb:14-22`);
98
+ medido con broker local: 311 examples, 0 failures, 0 pending en los seeds 1, 2 y 3.
99
+
81
100
  ### g. Link a incidente → test de regresión
82
101
 
83
102
  | incidente | test de regresión | ancla |
@@ -21,7 +21,7 @@ module BugBunny
21
21
  # Claves soportadas:
22
22
  # - `:type` — clase que debe responder `is_a?`
23
23
  # - `:required` — si `true`, nil o string vacío lanzan ConfigurationError
24
- # - `:range` — rango válido de valores (solo para Integer)
24
+ # - `:range` — rango válido de valores (solo para numéricos)
25
25
  VALIDATIONS = {
26
26
  host: { type: String, required: true },
27
27
  port: { type: Integer, required: true, range: 1..65_535 },
@@ -33,7 +33,9 @@ module BugBunny
33
33
  read_timeout: { type: Integer, range: 1..300 },
34
34
  write_timeout: { type: Integer, range: 1..300 },
35
35
  rpc_timeout: { type: Integer, range: 1..3_600 },
36
- channel_prefetch: { type: Integer, range: 1..10_000 }
36
+ channel_prefetch: { type: Integer, range: 1..10_000 },
37
+ drain_idle_timeout: { type: Integer, range: 1..3_600 },
38
+ drain_poll_interval: { type: Numeric, range: 0.01..10 }
37
39
  }.freeze
38
40
 
39
41
  # @return [String] Host o IP del servidor RabbitMQ (ej: 'localhost').
@@ -94,6 +96,14 @@ module BugBunny
94
96
  # @return [Integer] Intervalo en segundos para verificar la salud de la cola.
95
97
  attr_accessor :health_check_interval
96
98
 
99
+ # @return [Integer] Segundos sin entregas tras los cuales {BugBunny::Consumer#drain}
100
+ # da la cola por vacía y retorna (default: 5).
101
+ attr_accessor :drain_idle_timeout
102
+
103
+ # @return [Numeric] Cada cuántos segundos {BugBunny::Consumer#drain} revisa si se
104
+ # cumplió la ventana de inactividad (default: 0.1).
105
+ attr_accessor :drain_poll_interval
106
+
97
107
  # @return [String, nil] Ruta del archivo que se actualizará (touch) en cada health check exitoso.
98
108
  # Ideal para sondas (probes) de orquestadores como Docker Swarm o Kubernetes.
99
109
  # Si es `nil`, la funcionalidad de touchfile se desactiva.
@@ -175,6 +185,16 @@ module BugBunny
175
185
  # `Client#publish`.
176
186
  attr_accessor :return_raise
177
187
 
188
+ # @return [Boolean] Si `true` (default) y la gema corre dentro de Rails, el Railtie envuelve
189
+ # cada mensaje del Consumer con `Rails.application.executor.wrap`
190
+ # ({BugBunny::ConsumerMiddleware::RailsExecutor}): el estado por hilo (`CurrentAttributes`,
191
+ # la conexión de ActiveRecord) no pasa de un mensaje al siguiente.
192
+ # Fuera de Rails no tiene efecto.
193
+ #
194
+ # Se lee al terminar de inicializar la app, así que se apaga desde `config/initializers`.
195
+ # Apagalo si el consumidor ya envuelve cada mensaje por su cuenta.
196
+ attr_accessor :consumer_rails_executor
197
+
178
198
  # @!endgroup
179
199
 
180
200
  # Inicializa la configuración con valores por defecto seguros.
@@ -217,6 +237,7 @@ module BugBunny
217
237
 
218
238
  @consumer_middlewares = ConsumerMiddleware::Stack.new
219
239
  init_callback_defaults
240
+ init_drain_defaults
220
241
  end
221
242
 
222
243
  # Construye la URL de conexión AMQP basada en los atributos configurados.
@@ -253,6 +274,16 @@ module BugBunny
253
274
  @on_return = nil
254
275
  @nack_raise = true
255
276
  @return_raise = true
277
+ @consumer_rails_executor = true
278
+ end
279
+
280
+ # Defaults de {BugBunny::Consumer#drain}.
281
+ # Extraído de {#initialize} para mantener el ABC size dentro de los límites.
282
+ #
283
+ # @return [void]
284
+ def init_drain_defaults
285
+ @drain_idle_timeout = 5
286
+ @drain_poll_interval = 0.1
256
287
  end
257
288
 
258
289
  def validate_required!(attr, value, rules)
@@ -41,6 +41,16 @@ module BugBunny
41
41
  new(connection).subscribe(**args)
42
42
  end
43
43
 
44
+ # Método de conveniencia para instanciar y drenar en un solo paso.
45
+ #
46
+ # @param connection [Bunny::Session] Una conexión TCP activa a RabbitMQ. Es de quien
47
+ # llama: `drain` no la cierra (ver {#drain}).
48
+ # @param args [Hash] Argumentos que se pasarán al método {#drain}.
49
+ # @return [Integer] Cantidad de mensajes procesados.
50
+ def self.drain(connection:, **args)
51
+ new(connection).drain(**args)
52
+ end
53
+
44
54
  # Inicializa un nuevo consumidor.
45
55
  #
46
56
  # @param connection [Bunny::Session] Conexión nativa de Bunny.
@@ -68,40 +78,14 @@ module BugBunny
68
78
  attempt = 0
69
79
 
70
80
  begin
71
- # Declaración de Infraestructura
72
- x = session.exchange(name: exchange_name, type: exchange_type, opts: exchange_opts)
73
- q = session.queue(queue_name, queue_opts)
74
- q.bind(x, routing_key: routing_key)
75
-
76
- # 📊 LOGGING DE OBSERVABILIDAD: Calculamos las opciones finales para mostrarlas en consola
77
- final_x_opts = BugBunny::Session::DEFAULT_EXCHANGE_OPTIONS
78
- .merge(BugBunny.configuration.exchange_options || {})
79
- .merge(exchange_opts || {})
80
- final_q_opts = BugBunny::Session::DEFAULT_QUEUE_OPTIONS
81
- .merge(BugBunny.configuration.queue_options || {})
82
- .merge(queue_opts || {})
83
-
84
- safe_log(:info, 'consumer.start', queue: queue_name, queue_opts: final_q_opts)
85
- safe_log(:info, 'consumer.bound', exchange: exchange_name, exchange_type: exchange_type,
86
- routing_key: routing_key, exchange_opts: final_x_opts)
81
+ queue = declare_infrastructure(queue_name: queue_name, exchange_name: exchange_name,
82
+ routing_key: routing_key, exchange_type: exchange_type,
83
+ exchange_opts: exchange_opts, queue_opts: queue_opts)
87
84
 
88
85
  start_health_check(queue_name)
89
86
 
90
- q.subscribe(manual_ack: true, block: block) do |delivery_info, properties, body|
91
- trace_id = properties.correlation_id
92
- logger = BugBunny.configuration.logger
93
-
94
- core = lambda {
95
- if logger.respond_to?(:tagged)
96
- logger.tagged(trace_id) { process_message(delivery_info, properties, body) }
97
- elsif defined?(Rails) && Rails.logger.respond_to?(:tagged)
98
- Rails.logger.tagged(trace_id) { process_message(delivery_info, properties, body) }
99
- else
100
- process_message(delivery_info, properties, body)
101
- end
102
- }
103
-
104
- BugBunny.configuration.consumer_middlewares.call(delivery_info, properties, body, &core)
87
+ queue.subscribe(manual_ack: true, block: block) do |delivery_info, properties, body|
88
+ handle_delivery(delivery_info, properties, body)
105
89
  end
106
90
  rescue StandardError => e
107
91
  attempt += 1
@@ -126,6 +110,71 @@ module BugBunny
126
110
  shutdown
127
111
  end
128
112
 
113
+ # Consume la cola hasta vaciarla y retorna: el modo para correr un consumidor como job
114
+ # (Sidekiq, un Job de k8s) en vez de como un proceso eterno.
115
+ #
116
+ # A diferencia de `subscribe(block: false)`, que retorna al instante, este método
117
+ # bloquea mientras haya mensajes y vuelve cuando la cola queda quieta:
118
+ #
119
+ # 1. Si la cola tiene 0 mensajes al arrancar, retorna `0` sin esperar.
120
+ # 2. Si hay mensajes, se suscribe con `manual_ack: true` respetando `channel_prefetch`,
121
+ # igual que el modo bloqueante.
122
+ # 3. Termina cuando pasaron `drain_idle_timeout` segundos (ver {Configuration}) sin
123
+ # entregas y no queda ningún mensaje en proceso. Cancela el consumer y cierra el
124
+ # canal ({#shutdown}).
125
+ #
126
+ # **Mensajes que llegan mientras drena:** un mensaje que llega antes de que venza la
127
+ # ventana de inactividad se procesa en esta vuelta; lo que llega después queda para
128
+ # la próxima corrida. Una entrega ya recibida cuando se cancela se procesa antes de
129
+ # volver (Bunny drena su work pool al cancelar); si igual no llegara a ack-earse, vuelve
130
+ # a la cola (at-least-once, nunca se pierde).
131
+ #
132
+ # **Con un flujo sostenido, no retorna.** Si los mensajes llegan más seguido que
133
+ # `drain_idle_timeout`, la ventana nunca vence: la duración la decide el productor, no
134
+ # la cola que había al arrancar. Acotalo desde afuera (el timeout del job de Sidekiq,
135
+ # `activeDeadlineSeconds` en k8s), sabiendo que cortarlo a mitad de una entrega da
136
+ # redelivery.
137
+ #
138
+ # **Una entrega que falla sale de la cola.** Si un middleware o el manejo de error
139
+ # levanta antes del ack, se rechaza sin requeue, igual que los errores de
140
+ # `process_message`; no queda ocupando el prefetch.
141
+ #
142
+ # No tiene loop de reconexión ni health check: un job que falla lo reintenta el
143
+ # framework que lo corre. (Bunny sí recupera la conexión por su cuenta si
144
+ # `automatically_recover` está activo.)
145
+ #
146
+ # **La conexión es de quien llama:** `drain` cierra su canal al volver, no la conexión,
147
+ # porque puede ser compartida (un pool, la del publisher). Si la creaste para esta
148
+ # corrida, cerrala vos (ver el README).
149
+ #
150
+ # @param queue_name [String] Nombre de la cola a drenar.
151
+ # @param exchange_name [String] Nombre del exchange al cual enlazar la cola.
152
+ # @param routing_key [String] Patrón de enrutamiento (ej: 'users.*').
153
+ # @param exchange_type [String] Tipo de exchange ('direct', 'topic', 'fanout').
154
+ # @param exchange_opts [Hash] Opciones adicionales para el exchange (durable, auto_delete).
155
+ # @param queue_opts [Hash] Opciones adicionales para la cola (durable, auto_delete).
156
+ # @return [Integer] Cantidad de mensajes procesados en esta vuelta (incluye los rechazados:
157
+ # también salieron de la cola).
158
+ def drain(queue_name:, exchange_name:, routing_key:, exchange_type: 'direct', exchange_opts: {},
159
+ queue_opts: {})
160
+ started_at = monotonic_now
161
+ queue = declare_infrastructure(queue_name: queue_name, exchange_name: exchange_name,
162
+ routing_key: routing_key, exchange_type: exchange_type,
163
+ exchange_opts: exchange_opts, queue_opts: queue_opts)
164
+
165
+ pending_count = queue.message_count
166
+ safe_log(:info, 'consumer.drain_start', queue: queue_name, pending_count: pending_count)
167
+ return 0 if pending_count.zero?
168
+
169
+ processed_count = consume_until_idle(queue)
170
+
171
+ safe_log(:info, 'consumer.drain_finished', queue: queue_name, processed_count: processed_count,
172
+ duration_s: (monotonic_now - started_at).round(3))
173
+ processed_count
174
+ ensure
175
+ shutdown
176
+ end
177
+
129
178
  # Detiene el health check timer y cierra el canal de forma ordenada.
130
179
  #
131
180
  # Llamar explícitamente al hacer shutdown del worker (SIGTERM, at_exit, etc.).
@@ -141,6 +190,110 @@ module BugBunny
141
190
 
142
191
  private
143
192
 
193
+ # Declara exchange y cola, los enlaza y loguea las opciones efectivas.
194
+ #
195
+ # @param queue_name [String] Nombre de la cola.
196
+ # @param exchange_name [String] Nombre del exchange.
197
+ # @param routing_key [String] Patrón de enrutamiento del binding.
198
+ # @param exchange_type [String] Tipo de exchange.
199
+ # @param exchange_opts [Hash] Opciones del exchange para esta llamada.
200
+ # @param queue_opts [Hash] Opciones de la cola para esta llamada.
201
+ # @return [Bunny::Queue] La cola declarada y enlazada.
202
+ def declare_infrastructure(queue_name:, exchange_name:, routing_key:, exchange_type:, exchange_opts:, queue_opts:)
203
+ exchange = session.exchange(name: exchange_name, type: exchange_type, opts: exchange_opts)
204
+ queue = session.queue(queue_name, queue_opts)
205
+ queue.bind(exchange, routing_key: routing_key)
206
+
207
+ # 📊 LOGGING DE OBSERVABILIDAD: Calculamos las opciones finales para mostrarlas en consola
208
+ effective_exchange_opts = BugBunny::Session::DEFAULT_EXCHANGE_OPTIONS
209
+ .merge(BugBunny.configuration.exchange_options || {})
210
+ .merge(exchange_opts || {})
211
+ effective_queue_opts = BugBunny::Session::DEFAULT_QUEUE_OPTIONS
212
+ .merge(BugBunny.configuration.queue_options || {})
213
+ .merge(queue_opts || {})
214
+
215
+ safe_log(:info, 'consumer.start', queue: queue_name, queue_opts: effective_queue_opts)
216
+ safe_log(:info, 'consumer.bound', exchange: exchange_name, exchange_type: exchange_type,
217
+ routing_key: routing_key, exchange_opts: effective_exchange_opts)
218
+ queue
219
+ end
220
+
221
+ # Pasa una entrega por los middlewares y el logger con tags, y la procesa.
222
+ #
223
+ # @param delivery_info [Bunny::DeliveryInfo, Bunny::GetResponse] Metadatos de entrega.
224
+ # @param properties [Bunny::MessageProperties] Headers y propiedades AMQP.
225
+ # @param body [String] El payload crudo del mensaje.
226
+ # @return [void]
227
+ def handle_delivery(delivery_info, properties, body)
228
+ settled = false
229
+
230
+ core = lambda {
231
+ with_log_tags(properties.correlation_id) { process_message(delivery_info, properties, body) }
232
+ settled = true
233
+ }
234
+
235
+ BugBunny.configuration.consumer_middlewares.call(delivery_info, properties, body, &core)
236
+ rescue StandardError => e
237
+ settle_failed_delivery(delivery_info, settled, e)
238
+ end
239
+
240
+ # Corre el bloque con el `correlation_id` como tag del logger, si el logger los soporta.
241
+ #
242
+ # @param trace_id [String, nil]
243
+ # @return [Object] lo que devuelva el bloque
244
+ def with_log_tags(trace_id, &block)
245
+ logger = BugBunny.configuration.logger
246
+ if logger.respond_to?(:tagged)
247
+ logger.tagged(trace_id, &block)
248
+ elsif defined?(Rails) && Rails.logger.respond_to?(:tagged)
249
+ Rails.logger.tagged(trace_id, &block)
250
+ else
251
+ yield
252
+ end
253
+ end
254
+
255
+ # Una entrega cuyo procesamiento levantó FUERA del rescue de `process_message` (un
256
+ # middleware, o `handle_fatal_error`) quedaba sin ack ni reject: con prefetch 1 ocupaba
257
+ # el único lugar, el broker dejaba de entregar y `drain` volvía "con éxito" con la cola
258
+ # llena. Se rechaza sin requeue, igual que `process_message` hace con sus propios
259
+ # errores. Si ya se había resuelto (el error vino después del ack), sólo se loguea:
260
+ # rechazar un tag ya confirmado cierra el canal.
261
+ #
262
+ # @param delivery_info [Bunny::DeliveryInfo, Bunny::GetResponse] Metadatos de entrega.
263
+ # @param settled [Boolean] si `process_message` ya hizo ack o reject.
264
+ # @param error [StandardError] lo que levantó.
265
+ # @return [void]
266
+ def settle_failed_delivery(delivery_info, settled, error)
267
+ safe_log(:error, 'consumer.delivery_failed', settled: settled, **exception_metadata(error))
268
+ session.channel.reject(delivery_info.delivery_tag, false) unless settled
269
+ end
270
+
271
+ # Se suscribe sin bloquear y espera a que la cola quede quieta `drain_idle_timeout`
272
+ # segundos sin ningún mensaje en proceso; después cancela la suscripción.
273
+ #
274
+ # @param queue [Bunny::Queue] La cola ya declarada y enlazada.
275
+ # @return [Integer] Cantidad de mensajes procesados.
276
+ def consume_until_idle(queue)
277
+ idle_timeout = BugBunny.configuration.drain_idle_timeout
278
+ poll_interval = BugBunny.configuration.drain_poll_interval
279
+ tracker = BugBunny::DrainTracker.new
280
+
281
+ subscription = queue.subscribe(manual_ack: true, block: false) do |delivery_info, properties, body|
282
+ tracker.track { handle_delivery(delivery_info, properties, body) }
283
+ end
284
+
285
+ sleep poll_interval until tracker.idle?(idle_timeout)
286
+
287
+ subscription.cancel
288
+ sleep poll_interval while tracker.busy?
289
+ tracker.processed
290
+ end
291
+
292
+ # @return [Float] Reloj monotónico en segundos.
293
+ def monotonic_now
294
+ Process.clock_gettime(Process::CLOCK_MONOTONIC)
295
+ end
296
+
144
297
  # Procesa un mensaje individual recibido de la cola orquestando el ruteo declarativo.
145
298
  #
146
299
  # Realiza la orquestación completa: Parsing -> Reconocimiento de Ruta -> Ejecución -> Respuesta.
@@ -0,0 +1,33 @@
1
+ # frozen_string_literal: true
2
+
3
+ module BugBunny
4
+ module ConsumerMiddleware
5
+ # Envuelve cada mensaje con el executor de Rails, como hace Sidekiq con cada job.
6
+ #
7
+ # El Consumer procesa los mensajes en el hilo de trabajo de Bunny, que Rails no conoce. Sin
8
+ # el executor, lo que Rails guarda por hilo pasa de un mensaje al siguiente:
9
+ # - los `ActiveSupport::CurrentAttributes` (y lo que vive en ellos: tags, trazas, métricas);
10
+ # - la conexión de ActiveRecord, que el hilo retiene hasta morir en vez de devolverla al pool.
11
+ #
12
+ # Además, el executor prende la caché de queries de ActiveRecord durante el mensaje y la limpia al
13
+ # terminarlo (en el hilo de Bunny estaba apagada).
14
+ #
15
+ # Lo registra el Railtie al principio de la cadena (ver {Stack#prepend}) salvo que
16
+ # `config.consumer_rails_executor` sea `false`. Fuera de Rails no se carga.
17
+ #
18
+ # **Errores:** `executor.wrap` relanza lo que escapa del mensaje, así que sigue el camino de
19
+ # siempre (el Consumer lo rechaza sin requeue). En Rails >= 7.0, antes de relanzar, además lo
20
+ # reporta a `Rails.error` con `handled: false`.
21
+ #
22
+ # Si el hilo ya está dentro del executor, `wrap` no abre otro: sólo ejecuta el bloque.
23
+ class RailsExecutor < Base
24
+ # @param delivery_info [Bunny::DeliveryInfo]
25
+ # @param properties [Bunny::MessageProperties]
26
+ # @param body [String]
27
+ # @return [void]
28
+ def call(delivery_info, properties, body)
29
+ ::Rails.application.executor.wrap { @app.call(delivery_info, properties, body) }
30
+ end
31
+ end
32
+ end
33
+ end
@@ -61,6 +61,19 @@ module BugBunny
61
61
  self
62
62
  end
63
63
 
64
+ # Registra un middleware al principio de la cadena, para que envuelva a todos los demás. Thread-safe.
65
+ #
66
+ # Es para lo que tiene que quedar afuera de todo sin depender del orden en que se registran los
67
+ # demás: {RailsExecutor} va primero porque limpia el estado por hilo al arrancar, y un middleware
68
+ # que carga ese estado antes que él (el de tracing de ExisRay) lo perdería.
69
+ #
70
+ # @param middleware_class [Class] Clase que hereda de {Base}.
71
+ # @return [self]
72
+ def prepend(middleware_class)
73
+ @mutex.synchronize { @middlewares.unshift(middleware_class) }
74
+ self
75
+ end
76
+
64
77
  # @return [Boolean] `true` si no hay middlewares registrados. Thread-safe.
65
78
  def empty?
66
79
  @mutex.synchronize { @middlewares.empty? }
@@ -0,0 +1,54 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'concurrent'
4
+
5
+ module BugBunny
6
+ # Lleva la cuenta de un drenaje de {Consumer#drain}: cuántos mensajes se procesaron,
7
+ # cuántos están en proceso y cuándo fue la última actividad.
8
+ #
9
+ # Es thread-safe: las entregas corren en el work pool de Bunny y la espera en el hilo
10
+ # que llamó a `drain`.
11
+ #
12
+ # @api private
13
+ class DrainTracker
14
+ # @param clock [#call] Reloj monotónico en segundos (inyectable para tests).
15
+ def initialize(clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
16
+ @clock = clock
17
+ @processed = Concurrent::AtomicFixnum.new(0)
18
+ @in_flight = Concurrent::AtomicFixnum.new(0)
19
+ @last_activity = Concurrent::AtomicReference.new(clock.call)
20
+ end
21
+
22
+ # Envuelve el procesamiento de una entrega. Cuenta la entrega como procesada aunque
23
+ # el bloque levante: {Consumer#handle_delivery} rechaza la que falla antes del ack, así
24
+ # que en todos los caminos el mensaje ya salió de la cola (ack o reject).
25
+ #
26
+ # @yield El procesamiento de la entrega.
27
+ # @return [void]
28
+ def track
29
+ @in_flight.increment
30
+ yield
31
+ ensure
32
+ @processed.increment
33
+ @last_activity.set(@clock.call)
34
+ @in_flight.decrement
35
+ end
36
+
37
+ # @return [Boolean] `true` si hay alguna entrega en proceso.
38
+ def busy?
39
+ @in_flight.value.positive?
40
+ end
41
+
42
+ # @param idle_timeout [Numeric] Segundos sin actividad.
43
+ # @return [Boolean] `true` si no hay nada en proceso y pasaron `idle_timeout` segundos
44
+ # desde la última actividad.
45
+ def idle?(idle_timeout)
46
+ !busy? && @clock.call - @last_activity.get >= idle_timeout
47
+ end
48
+
49
+ # @return [Integer] Entregas procesadas hasta ahora.
50
+ def processed
51
+ @processed.value
52
+ end
53
+ end
54
+ end
@@ -8,6 +8,7 @@ module BugBunny
8
8
  # Esta clase es responsable de:
9
9
  # 1. Registrar la carpeta `app/rabbit` en el autoloader de Rails (Zeitwerk).
10
10
  # 2. Gestionar la seguridad de las conexiones durante el "forking" de procesos (Puma/Spring).
11
+ # 3. Envolver cada mensaje del Consumer con el executor de Rails (ver {ConsumerMiddleware::RailsExecutor}).
11
12
  #
12
13
  # @see https://guides.rubyonrails.org/engines.html#railtie
13
14
  class Railtie < ::Rails::Railtie
@@ -34,12 +35,27 @@ module BugBunny
34
35
  end
35
36
  end
36
37
 
37
- # 3. Rake tasks (bug_bunny:sync)
38
+ # 3. Executor de Rails alrededor de cada mensaje del Consumer
39
+ #
40
+ # El Consumer procesa en el hilo de Bunny, que Rails no conoce: sin esto, el estado por hilo
41
+ # pasa de un mensaje al siguiente. Va al principio de la cadena (`prepend`, no `use`) para que
42
+ # envuelva también a los middlewares que cargan ese estado, como el de tracing de ExisRay, que
43
+ # se registra en su propio `after_initialize` y en un orden que no controlamos.
44
+ config.after_initialize do
45
+ # Sin un `BugBunny.configure` previo, vale la configuración por default; un `configure` posterior la reusa.
46
+ BugBunny.configuration ||= BugBunny::Configuration.new
47
+ if BugBunny.configuration.consumer_rails_executor
48
+ require_relative 'consumer_middleware/rails_executor'
49
+ BugBunny.consumer_middlewares.prepend(BugBunny::ConsumerMiddleware::RailsExecutor)
50
+ end
51
+ end
52
+
53
+ # 4. Rake tasks (bug_bunny:sync)
38
54
  rake_tasks do
39
55
  load File.expand_path('../tasks/bug_bunny.rake', __dir__)
40
56
  end
41
57
 
42
- # 4. Hook de Spring (Preloader)
58
+ # 5. Hook de Spring (Preloader)
43
59
  if defined?(Spring)
44
60
  Spring.after_fork do
45
61
  BugBunny.disconnect
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module BugBunny
4
- VERSION = '5.1.1'
4
+ VERSION = '5.3.0'
5
5
  end