bug_bunny 5.2.0 → 5.4.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.
- checksums.yaml +4 -4
- data/.rspec +2 -0
- data/AGENTS.md +3 -2
- data/CHANGELOG.md +29 -0
- data/CLAUDE.md +1 -1
- data/README.md +42 -3
- data/Rakefile +9 -1
- data/docs/behavior/behavior.md +25 -3
- data/docs/config/configuracion.md +53 -43
- data/docs/errors/errors.md +4 -2
- data/docs/release/release.md +13 -9
- data/docs/test/testing.md +16 -6
- data/lib/bug_bunny/configuration.rb +11 -0
- data/lib/bug_bunny/consumer_middleware/rails_executor.rb +33 -0
- data/lib/bug_bunny/consumer_middleware.rb +13 -0
- data/lib/bug_bunny/railtie.rb +14 -3
- data/lib/bug_bunny/version.rb +1 -1
- data/lib/generators/bug_bunny/install/install_generator.rb +0 -42
- data/skill/SKILL.md +13 -7
- data/skill/references/consumer.md +9 -0
- data/skill/references/testing.md +4 -1
- data/spec/rails/app.rb +70 -0
- data/spec/rails/consumer_rails_executor_spec.rb +165 -0
- data/spec/rails/install_generator_spec.rb +66 -0
- data/spec/rails/rails_helper.rb +6 -0
- data/spec/rails/railtie_rake_tasks_spec.rb +21 -0
- data/spec/unit/configuration_spec.rb +6 -0
- data/spec/unit/consumer_middleware_spec.rb +13 -0
- data/spec/unit/consumer_rails_executor_outside_rails_spec.rb +19 -0
- metadata +53 -4
- data/lib/tasks/bug_bunny.rake +0 -50
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: d8ca8ec1c80982fc9a195a414e2af1039994e66ca1c10d33b3de36a3bc5cdc6b
|
|
4
|
+
data.tar.gz: 5b42f7076a1330857b18395146c6a423d8abdf8f52b53f06081adbc7e915995a
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 2bdac4c3895b7fdb2b092cb37eb96be256434a80d097226d65a8b471f16a1a40c61fac3eac46b5175e4341abcd476a53e7dca84b5244250123aa2d252eb656f5
|
|
7
|
+
data.tar.gz: 4ceb135c73aee74d9df64828d46a420f1b3463f162bfab2fcb293a361e88222366faaac211c96bf8965448f4972a7c015d58797a8f9a113e7dc555827a2c3209
|
data/.rspec
ADDED
data/AGENTS.md
CHANGED
|
@@ -12,7 +12,7 @@ proyecto y convenciones de equipo, ver `CLAUDE.md`. Para la entrada humana, ver
|
|
|
12
12
|
|
|
13
13
|
| capa | artefacto | estado | qué responde |
|
|
14
14
|
|---|---|---|---|
|
|
15
|
-
| Comportamiento | `docs/behavior/behavior.md` | completo (
|
|
15
|
+
| Comportamiento | `docs/behavior/behavior.md` | completo (8 flujos) | secuencias de publish/RPC/consume/confirms, contrato de error-wrapping |
|
|
16
16
|
| Glosario | `docs/glossary/glossary.md` | parcial (acreta por PR) | término de negocio → binding físico en `lib/` |
|
|
17
17
|
| Errores | `docs/errors/errors.md` | completo (§a/b/d estructura + §c política inferida) | jerarquía de excepciones públicas, mapeo `status→excepción`, shape del payload, política retry |
|
|
18
18
|
| Configuración | `docs/config/configuracion.md` | completo (estructura + enrich §f/g/h) | opciones de `Configuration`, defaults, failure-mode/threading, inyecciones del `Railtie`, ENV sugeridas |
|
|
@@ -38,6 +38,7 @@ a YARD/specs/CHANGELOG. Pendiente de **verificación humana** (inferencias):
|
|
|
38
38
|
|
|
39
39
|
- Ruby: `.ruby-version` · gemas: `Gemfile.lock` · manager: chruby + Bundler.
|
|
40
40
|
- Antes de commitear: `bundle exec rubocop -a` (base `rubocop-rails-omakase`),
|
|
41
|
-
`bundle exec
|
|
41
|
+
`bundle exec rake` (las dos suites: `spec/` y `spec/rails/`, cada una en su proceso; `bundle exec rspec` solo
|
|
42
|
+
corre `spec/`, sin Rails), YARD incremental (`bundle exec yard stats --list-undoc`).
|
|
42
43
|
- Releases: `/gem-release` (el GitHub Action publica a RubyGems al pushear tag `v*`).
|
|
43
44
|
- Doc por-PR: si tocás una capa, mové su artefacto en el mismo PR (régimen RFC-001).
|
data/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,34 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## [5.4.0] - 2026-11-18
|
|
4
|
+
|
|
5
|
+
### ⚠️ Cambio de conducta — la gema ya no escribe `CLAUDE.md`
|
|
6
|
+
- **`rails generate bug_bunny:install` ya no crea ni modifica el `CLAUDE.md` del repo que usa la gema**, y **se borró la tarea `rake bug_bunny:sync`** (y su carga en el Railtie), que lo creaba o reescribía en `Dir.pwd`. Los repos del fleet no llevan configuración de agente: la trae el reino `hefesto` (sequre/hefesto#724, lector L11). Además, el bloque que escribían apuntaba a `docs/ai`, que no existe desde 4.8.1. (#72, #73) — @gedera
|
|
7
|
+
- **A mirar si consumís:** quien llame `rake bug_bunny:sync` (en `bin/setup`, un Dockerfile o CI) recibe `Don't know how to build task 'bug_bunny:sync'` al actualizar: borrá esa llamada. Medido el 2026-11-18: ningún repo de `sequre` la llama. Un `CLAUDE.md` que ya tenga el bloque `### bug_bunny` queda como está; nadie lo vuelve a actualizar.
|
|
8
|
+
|
|
9
|
+
### Tests
|
|
10
|
+
- `spec/rails/`: el generador no crea ni modifica `CLAUDE.md` y sigue creando el inicializador y `app/bug_bunny/controllers/`; el Railtie no define `bug_bunny:sync`. Fallan contra 5.3.0. (#73) — @gedera
|
|
11
|
+
|
|
12
|
+
### Documentación
|
|
13
|
+
- `docs/config/configuracion.md` (§i, sin la inyección `rake_tasks`) y `skill/SKILL.md` (FAQ del generador). (#73) — @gedera
|
|
14
|
+
|
|
15
|
+
## [5.3.0] - 2026-10-16
|
|
16
|
+
|
|
17
|
+
### Nuevas funcionalidades
|
|
18
|
+
- **Dentro de Rails, cada mensaje del Consumer corre dentro del executor de Rails (#70):** el railtie registra `BugBunny::ConsumerMiddleware::RailsExecutor`, que envuelve cada mensaje con `Rails.application.executor.wrap`, como Sidekiq con cada job. El Consumer procesa en el hilo de trabajo de Bunny, que Rails no conoce, así que hasta ahora lo que Rails guarda por hilo pasaba de un mensaje al siguiente: los `CurrentAttributes` (tags de Sentry, contexto de traza, métricas por ejecución) y la conexión de ActiveRecord (el hilo la retenía en vez de devolverla al pool). Fuera de Rails no se registra nada y la gema se comporta como antes. (#70, #71) — @Pslp
|
|
19
|
+
- **`config.consumer_rails_executor`** (default `true`): con `false`, el railtie no registra el middleware. Se lee al terminar de inicializar la app, así que se apaga desde `config/initializers`. Si la app no llamó a `BugBunny.configure` antes de ese momento, el railtie usa la configuración por default en vez de caerse al bootear. — @Pslp
|
|
20
|
+
- **`ConsumerMiddleware::Stack#prepend`:** registra un middleware al principio de la cadena. El del executor va primero así, para envolver también a los middlewares que cargan estado por hilo (el de tracing de ExisRay se registra en su propio `after_initialize`, en un orden que no controlamos). — @Pslp
|
|
21
|
+
|
|
22
|
+
### ⚠️ Cambio de conducta (dentro de Rails)
|
|
23
|
+
- **Rails ≥ 7.0 — un error que escapa del procesamiento de un mensaje ahora además se reporta a `Rails.error`** con `handled: false`, porque es lo que hace `executor.wrap` antes de relanzar. El camino del mensaje no cambia: se rechaza sin requeue, como desde 5.2.0. Los errores dentro de las acciones del controller los sigue rescatando el Consumer y no se ven afectados. **A mirar si consumís:** si tenés un subscriber de `Rails.error` (el de Sentry, por ejemplo), esos errores ahora aparecen ahí. Para volver a la conducta anterior: `config.consumer_rails_executor = false`. — @Pslp
|
|
24
|
+
- **La caché de queries de ActiveRecord queda prendida durante cada mensaje** y se limpia al terminarlo: es lo que hace el executor (`ActiveRecord::QueryCache::ExecutorHooks`). En el hilo de Bunny estaba apagada. **A mirar si consumís:** un handler que relee la misma fila dentro de un mensaje esperando que otro proceso la cambie (un poll) ahora recibe el valor cacheado; usá `ActiveRecord::Base.uncached { … }` ahí. Se vuelve a la conducta anterior con `config.consumer_rails_executor = false`. — @Pslp
|
|
25
|
+
|
|
26
|
+
### Tests
|
|
27
|
+
- `spec/rails/`: una app Rails mínima (ActiveRecord sobre SQLite en memoria) prueba el railtie con Rails de verdad. Corre en su propio proceso (`rake spec:rails`), para que el resto de la suite siga probando la gema fuera de Rails; `rake` sin argumentos corre las dos, y `rspec` pelado corre `spec/` (un `.rspec` excluye `spec/rails/` salvo que se lo pida: `rspec spec/rails` la corre). Suma `railties`, `activerecord` y `sqlite3` como dependencias de desarrollo. — @Pslp
|
|
28
|
+
|
|
29
|
+
### Documentación
|
|
30
|
+
- README, `skill/` y los artefactos de `docs/` (configuración, comportamiento, tests, errores) describen el executor, la opción y los dos cambios de conducta; las metas que tocó #70 se re-anclaron a `67cca83`. — @Pslp
|
|
31
|
+
|
|
3
32
|
## [5.2.0] - 2026-09-29
|
|
4
33
|
|
|
5
34
|
### Nuevas funcionalidades
|
data/CLAUDE.md
CHANGED
|
@@ -61,7 +61,7 @@ BugBunny es una gema Ruby que implementa una capa de enrutamiento RESTful sobre
|
|
|
61
61
|
|
|
62
62
|
### Testing
|
|
63
63
|
- Framework: RSpec
|
|
64
|
-
- Correr: `bundle exec rspec`
|
|
64
|
+
- Correr: `bundle exec rake` (las dos suites: `spec/` y `spec/rails/`, cada una en su proceso; `bundle exec rspec` solo corre `spec/`, sin Rails)
|
|
65
65
|
- Todo código nuevo debe tener tests.
|
|
66
66
|
|
|
67
67
|
### Releases o Nuevas versiones
|
data/README.md
CHANGED
|
@@ -173,6 +173,10 @@ BugBunny.configure do |config|
|
|
|
173
173
|
config.drain_idle_timeout = 5
|
|
174
174
|
config.drain_poll_interval = 0.1
|
|
175
175
|
|
|
176
|
+
# Rails only — wrap every consumed message in Rails.application.executor (default: true).
|
|
177
|
+
# See "Rails executor around each message" below. Set it from config/initializers.
|
|
178
|
+
config.consumer_rails_executor = true
|
|
179
|
+
|
|
176
180
|
# Publisher Confirms — fail-loud defaults (both flags default to true).
|
|
177
181
|
# Set to false to restore legacy log-only behavior.
|
|
178
182
|
config.nack_raise = true # broker NACK → raise BugBunny::PublishNacked
|
|
@@ -362,6 +366,41 @@ end
|
|
|
362
366
|
BugBunny.consumer_middlewares.use TracingMiddleware
|
|
363
367
|
```
|
|
364
368
|
|
|
369
|
+
`use` appends to the chain; `prepend` puts a middleware first, wrapping every other one.
|
|
370
|
+
|
|
371
|
+
### Rails executor around each message
|
|
372
|
+
|
|
373
|
+
Inside Rails, the railtie registers `BugBunny::ConsumerMiddleware::RailsExecutor` **first** in the chain. It wraps every
|
|
374
|
+
message in `Rails.application.executor.wrap`, the same way Sidekiq wraps each job. The consumer processes messages on
|
|
375
|
+
Bunny's worker thread, which Rails does not know about; without the executor, what Rails keeps per thread survives from
|
|
376
|
+
one message to the next:
|
|
377
|
+
|
|
378
|
+
- `ActiveSupport::CurrentAttributes` (and whatever lives in them: Sentry tags, trace context, per-run metrics);
|
|
379
|
+
- the ActiveRecord connection, which the thread keeps until it dies instead of returning it to the pool.
|
|
380
|
+
|
|
381
|
+
It goes first (`prepend`, not `use`) so that it also wraps the middlewares that load per-thread state, like ExisRay's
|
|
382
|
+
tracing middleware. Outside Rails nothing is registered and the consumer behaves as before.
|
|
383
|
+
|
|
384
|
+
#### ⚠️ Behavior change
|
|
385
|
+
|
|
386
|
+
**Errors that escape a message (Rails ≥ 7.0).**
|
|
387
|
+
An error that escapes the processing of a message (from a middleware, or from `handle_fatal_error`) still ends the same
|
|
388
|
+
way: the delivery is rejected without requeue. **It is now also reported to `Rails.error`** with `handled: false`, because that is what `executor.wrap` does before re-raising. If you have a `Rails.error` subscriber
|
|
389
|
+
(e.g. Sentry's), that error shows up there. Errors inside your controller actions are rescued by the consumer as
|
|
390
|
+
before and are not affected.
|
|
391
|
+
|
|
392
|
+
**The ActiveRecord query cache is on during each message**, and cleared when it ends: that is what the executor does
|
|
393
|
+
(`ActiveRecord::QueryCache::ExecutorHooks`). On Bunny's thread it used to be off. A handler that re-reads the same row
|
|
394
|
+
within one message, waiting for another process to change it (a poll), now gets the cached value; wrap that read in
|
|
395
|
+
`ActiveRecord::Base.uncached { … }`.
|
|
396
|
+
|
|
397
|
+
To turn it off (for example, if your consumer already wraps each message itself):
|
|
398
|
+
|
|
399
|
+
```ruby
|
|
400
|
+
# config/initializers/bug_bunny.rb
|
|
401
|
+
BugBunny.configure { |config| config.consumer_rails_executor = false }
|
|
402
|
+
```
|
|
403
|
+
|
|
365
404
|
---
|
|
366
405
|
|
|
367
406
|
## Observability
|
|
@@ -459,16 +498,16 @@ end
|
|
|
459
498
|
|
|
460
499
|
Artefactos de detalle (modelo `dev-*`, RFC-001). El README indexa; no duplica.
|
|
461
500
|
|
|
462
|
-
Anclado a `v5.
|
|
501
|
+
Anclado a `v5.4.0`.
|
|
463
502
|
|
|
464
503
|
| Capa | Artefacto | Estado |
|
|
465
504
|
|---|---|---|
|
|
466
505
|
| Glosario | [docs/glossary/glossary.md](docs/glossary/glossary.md) | parcial, acreta por PR |
|
|
467
|
-
| Comportamiento | [docs/behavior/behavior.md](docs/behavior/behavior.md) | completa —
|
|
506
|
+
| Comportamiento | [docs/behavior/behavior.md](docs/behavior/behavior.md) | completa — 8 flujos (backfill on-demand) |
|
|
468
507
|
| Configuración | [docs/config/configuracion.md](docs/config/configuracion.md) | §a-§e/§i estructura + §f/§g/§h enrich — completa |
|
|
469
508
|
| Dependencias consumidas | [docs/consumed/rabbitmq.md](docs/consumed/rabbitmq.md) | §a/§b/§d estructura + §c/§e enrich |
|
|
470
509
|
| Errores | [docs/errors/errors.md](docs/errors/errors.md) | §a/§b/§d completas; §c política inferida (verificación humana pendiente) |
|
|
471
|
-
| Test | [docs/test/testing.md](docs/test/testing.md) | §a-§h —
|
|
510
|
+
| Test | [docs/test/testing.md](docs/test/testing.md) | §a-§h — 18 unit / 8 integration / 1 rails (`spec/rails/`, en su propio proceso) |
|
|
472
511
|
| Release | [docs/release/release.md](docs/release/release.md) | completa (régimen gema: build→publish; §e/f/g n/a) |
|
|
473
512
|
| Datos | — | n/a — gema sin DB (sin schema/models) |
|
|
474
513
|
| Eventos | — | n/a — la gema **es** el transporte; no declara catálogo de eventos de dominio propio |
|
data/Rakefile
CHANGED
|
@@ -4,6 +4,7 @@ require 'rspec/core/rake_task'
|
|
|
4
4
|
|
|
5
5
|
RSpec::Core::RakeTask.new(:spec) do |t|
|
|
6
6
|
t.rspec_opts = '--require spec_helper'
|
|
7
|
+
t.exclude_pattern = 'spec/rails/**/*_spec.rb'
|
|
7
8
|
end
|
|
8
9
|
|
|
9
10
|
RSpec::Core::RakeTask.new('spec:unit') do |t|
|
|
@@ -16,6 +17,12 @@ RSpec::Core::RakeTask.new('spec:integration') do |t|
|
|
|
16
17
|
t.rspec_opts = '--require spec_helper'
|
|
17
18
|
end
|
|
18
19
|
|
|
20
|
+
# Los specs que necesitan Rails (el Railtie) bootean una app propia, y Rails se inicializa una vez por
|
|
21
|
+
# proceso: corren aparte, para que el resto de la suite siga probando la gema fuera de Rails.
|
|
22
|
+
RSpec::Core::RakeTask.new('spec:rails') do |t|
|
|
23
|
+
t.pattern = 'spec/rails/**/*_spec.rb'
|
|
24
|
+
end
|
|
25
|
+
|
|
19
26
|
# Mantiene la tarea :test apuntando a los tests de integración legacy de Minitest
|
|
20
27
|
Rake::TestTask.new(:test) do |t|
|
|
21
28
|
t.libs << 'test'
|
|
@@ -25,4 +32,5 @@ Rake::TestTask.new(:test) do |t|
|
|
|
25
32
|
t.warning = false
|
|
26
33
|
end
|
|
27
34
|
|
|
28
|
-
|
|
35
|
+
# Las dos suites, cada una en su proceso: es lo que corren `quality-code` y `gem-release`.
|
|
36
|
+
task default: [:spec, 'spec:rails']
|
data/docs/behavior/behavior.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Comportamiento — bug_bunny
|
|
2
2
|
|
|
3
|
-
> meta: artefacto `comportamiento` · RFC-007 (cadencia incremental default / completo on-demand) · generado dev-enrich 1.3.0 (backfill on-demand) · anclado a `
|
|
3
|
+
> meta: artefacto `comportamiento` · RFC-007 (cadencia incremental default / completo on-demand) · generado dev-enrich 1.3.0 (backfill on-demand) · anclado a `67cca83` (squash de #71 en `main`; antes `35b075a`) · cobertura: completa (8 flujos) · verificado por humano 2026-05-18 (base) · 2026-05-26 (refresco scoped: contrato de error wrapping post-#49) — incremento 2026-09-28 (#64, flujo `drain` + re-mapeo de `file:line`): escrito por el agente, **sin verificación humana todavía** — incremento 2026-10-16 (#70, flujo «Executor de Rails alrededor de cada mensaje»; re-anclado a `67cca83` en el release 5.3.0): escrito por el agente, **sin verificación humana todavía**
|
|
4
4
|
|
|
5
5
|
## 1. Resumen
|
|
6
6
|
|
|
@@ -17,8 +17,9 @@ Flujos de ejecución de la gema. Generado en **modo completo on-demand** (RFC-00
|
|
|
17
17
|
| Consumer drain (drenar y salir) | **documentado** | `consumer.rb:158-176,271-290`, `drain_tracker.rb:28-47` |
|
|
18
18
|
| Error handling / RemoteError | **documentado** | `consumer.rb:473-482`, `remote_error.rb`, `raise_error.rb:32-65` |
|
|
19
19
|
| Client middleware stack (onion) | **documentado** | `middleware/stack.rb:43-47`, `base.rb:35-43` |
|
|
20
|
+
| Executor de Rails alrededor de cada mensaje | **documentado** | `railtie.rb:44-51`, `consumer_middleware/rails_executor.rb:28-30`, `consumer.rb:227-238` |
|
|
20
21
|
|
|
21
|
-
Cobertura completa a `
|
|
22
|
+
Cobertura completa a `67cca83`. Acreta incremental en cada PR que toque un flujo (default RFC-007). Ausencia futura ≠ inexistencia.
|
|
22
23
|
|
|
23
24
|
## 2. Cuerpo
|
|
24
25
|
|
|
@@ -110,7 +111,7 @@ sequenceDiagram
|
|
|
110
111
|
C->>H: start_health_check (touch file)
|
|
111
112
|
C->>BR: q.subscribe(manual_ack, block:true) — LOOP
|
|
112
113
|
loop por mensaje
|
|
113
|
-
BR->>C: deliver → consumer_middlewares → process_message
|
|
114
|
+
BR->>C: deliver → consumer_middlewares (en Rails: RailsExecutor primero) → process_message
|
|
114
115
|
end
|
|
115
116
|
H-->>S: cada interval: queue_declare(passive:true)
|
|
116
117
|
H-->>S: falla → cierra session (fuerza reconnect)
|
|
@@ -146,6 +147,27 @@ sequenceDiagram
|
|
|
146
147
|
```
|
|
147
148
|
Contexto: `consumer.rb:158-176` (`drain`), `consumer.rb:271-290` (`consume_until_idle`), `drain_tracker.rb:28-47`. **Mensajes que llegan mientras drena:** entran en esta vuelta si llegan antes de que venza la ventana; los posteriores quedan para la próxima corrida. Una entrega ya recibida al cancelar se procesa antes de volver (Bunny drena su work pool al cancelar — leído de la fuente de Bunny 2.24.0, no medido); si igual no se ack-eara, **vuelve a la cola** (at-least-once). El conteo devuelto incluye los rechazados. **Una entrega que falla fuera del rescue de `process_message`** (un middleware, `handle_fatal_error`) se rechaza sin requeue en `handle_delivery` y se loguea `consumer.delivery_failed`; antes quedaba sin ack, trababa el prefetch y `drain` volvía "con éxito" con la cola llena (medido en el review de #65). **Con un flujo sostenido no retorna:** si los mensajes llegan más seguido que `drain_idle_timeout` la ventana no vence — la duración la decide el productor; se acota desde afuera (timeout del job). **La conexión es del llamador:** `drain` cierra el canal, no la conexión. **Distinto de `subscribe(block: false)`:** ese modo retorna al instante y el `ensure shutdown` cierra el canal, así que no consume nada (medido en #64).
|
|
148
149
|
|
|
150
|
+
### Flujo: Executor de Rails alrededor de cada mensaje
|
|
151
|
+
Dentro de Rails, cada entrega corre dentro de `Rails.application.executor.wrap`, como un job de Sidekiq. El Consumer procesa en el hilo de trabajo de Bunny, que Rails no conoce: sin esto, el estado por hilo pasa de un mensaje al siguiente (#70).
|
|
152
|
+
|
|
153
|
+
```mermaid
|
|
154
|
+
sequenceDiagram
|
|
155
|
+
participant BR as RabbitMQ
|
|
156
|
+
participant C as Consumer#handle_delivery
|
|
157
|
+
participant X as RailsExecutor
|
|
158
|
+
participant M as otros middlewares (p. ej. tracing de ExisRay)
|
|
159
|
+
participant P as process_message
|
|
160
|
+
BR->>C: deliver (hilo de Bunny)
|
|
161
|
+
C->>X: consumer_middlewares.call
|
|
162
|
+
X->>X: executor.wrap — al entrar: reset de CurrentAttributes · prende la caché de queries de AR
|
|
163
|
+
X->>M: @app.call
|
|
164
|
+
M->>P: core: rutea, llama al controller, ack/reject, reply RPC
|
|
165
|
+
P-->>X: vuelve
|
|
166
|
+
X->>X: al salir: reset de CurrentAttributes · la conexión de AR vuelve al pool · se apaga y limpia la caché de queries
|
|
167
|
+
Note over C: un error que escapa: wrap lo relanza (en Rails ≥ 7.0, antes lo reporta a Rails.error) → rescue de handle_delivery → reject sin requeue
|
|
168
|
+
```
|
|
169
|
+
Contexto: `railtie.rb:44-51` (registro en `after_initialize`, sólo si `config.consumer_rails_executor`), `consumer_middleware.rb:72-75` (`Stack#prepend`), `consumer_middleware/rails_executor.rb:28-30` (`wrap`), `consumer.rb:227-238` (`handle_delivery`: la cadena y su `rescue`). **Va primero** (`prepend`) porque el reset al entrar borraría el estado que un middleware anterior ya cargó: el de tracing de ExisRay carga `ExisRay::Tracer` (un `CurrentAttributes`) y se registra en su propio `after_initialize`, en un orden que no controlamos. El ack/reject queda adentro del wrap (vive en `process_message`); el `rescue` de `handle_delivery`, afuera. Si el hilo ya está dentro del executor, `wrap` no abre otro. **Fuera de Rails** el Railtie no se carga y la cadena no cambia. Probado con Rails de verdad en `spec/rails/consumer_rails_executor_spec.rb` (Rails 8.1.4, la versión que corre la suite). **Cambio de conducta:** la caché de queries, que en el hilo de Bunny estaba apagada, queda prendida durante cada mensaje (`ActiveRecord::QueryCache::ExecutorHooks`).
|
|
170
|
+
|
|
149
171
|
### Flujo: Error handling / RemoteError
|
|
150
172
|
Excepción no manejada en controller → serializada (clase/mensaje/backtrace[0..25]) → reply 500 → reconstruida client-side por `Middleware::RaiseError`.
|
|
151
173
|
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# Configuración — bug_bunny
|
|
2
2
|
|
|
3
3
|
> meta: artefacto configuración · RFC-012 · generado `arch-structure` (inventario
|
|
4
|
-
> §a-§e/§i) + `arch-enrich` (§f/§g/§h/§j) · anclado a `
|
|
4
|
+
> §a-§e/§i) + `arch-enrich` (§f/§g/§h/§j) · anclado a `67cca83` (squash de #71 en `main`),
|
|
5
5
|
> `lib/bug_bunny/configuration.rb`, `lib/bug_bunny.rb`, `lib/bug_bunny/railtie.rb`,
|
|
6
6
|
> `lib/bug_bunny/consumer.rb`,
|
|
7
7
|
> `lib/generators/bug_bunny/install/templates/initializer.rb` · fecha 2026-06-30
|
|
@@ -9,6 +9,14 @@
|
|
|
9
9
|
> §j n/a. Incremento 2026-09-28 (#64): `drain_idle_timeout`/`drain_poll_interval`,
|
|
10
10
|
> anclados a `configuration.rb:37-38,99-105,273-275` y `consumer.rb:271-290`; todas las
|
|
11
11
|
> citas `file:line` re-mapeadas al árbol de `35b075a` (el refactor de #64 las corrió).
|
|
12
|
+
> Incremento 2026-10-16 (#70): `consumer_rails_executor` (`configuration.rb:196,277`,
|
|
13
|
+
> `railtie.rb:44-51`); las citas de `configuration.rb` re-mapeadas por contenido (el atributo
|
|
14
|
+
> nuevo corrió +10/+11 todo lo que viene después) y las de `railtie.rb` (§i). Re-anclado a
|
|
15
|
+
> `67cca83` en el release 5.3.0: entre `35b075a` y `67cca83` sólo cambiaron los archivos de #70
|
|
16
|
+
> (re-mapeados) y `version.rb` (no citado).
|
|
17
|
+
> Incremento 2026-11-18 (#72): se sacó la inyección `rake_tasks` (`bug_bunny:sync`) del §i; la
|
|
18
|
+
> cita de `Spring.after_fork` pasó de `:59-63` a `:54-58` (árbol de `336f1eb`, release 5.4.0). Escrito por el agente, sin verificación
|
|
19
|
+
> humana todavía.
|
|
12
20
|
|
|
13
21
|
## 1. Resumen
|
|
14
22
|
|
|
@@ -22,12 +30,12 @@ en `lib/`**; el `ENV.fetch` vive en el **template** que sugiere al consumidor
|
|
|
22
30
|
|
|
23
31
|
### a. Hecho verificable
|
|
24
32
|
|
|
25
|
-
- **Total opciones (`Configuration`):**
|
|
26
|
-
2026-
|
|
33
|
+
- **Total opciones (`Configuration`):** 33 (32 `attr_accessor` + 1 `attr_reader`; medido
|
|
34
|
+
2026-10-16, con `consumer_rails_executor` de #70 — el `29` anterior ya estaba desfasado del código antes de #64).
|
|
27
35
|
- **Validadas requeridas (`VALIDATIONS`, `configuration.rb:25-39`):** 5 (`host`,
|
|
28
36
|
`port`, `username`, `password`, `vhost` — `required: true`; igual tienen
|
|
29
37
|
default, `validate!` exige no-vacío).
|
|
30
|
-
- **Con default:**
|
|
38
|
+
- **Con default:** 33 (todas; defaults en `initialize`/`init_callback_defaults`/`init_drain_defaults`).
|
|
31
39
|
- **Con rango validado:** 9 (`port`, `heartbeat`, `connection_timeout`,
|
|
32
40
|
`read_timeout`, `write_timeout`, `rpc_timeout`, `channel_prefetch`,
|
|
33
41
|
`drain_idle_timeout`, `drain_poll_interval`).
|
|
@@ -41,38 +49,39 @@ Origen `code-default` salvo nota. Consumidor = `configuration.rb` (default en
|
|
|
41
49
|
|
|
42
50
|
| nombre | tipo | requerida | default | origen | consumidor | secret? |
|
|
43
51
|
|---|---|---|---|---|---|---|
|
|
44
|
-
| `host` | String | sí (validate!) | `'127.0.0.1'` | code-default | `configuration.rb:
|
|
45
|
-
| `port` | Integer | sí (validate!, 1..65535) | `5672` | code-default | `:
|
|
46
|
-
| `username` | String | sí (validate!) | `'guest'` | code-default | `:
|
|
47
|
-
| `password` | String | sí (validate!) | `'guest'` | code-default | `:
|
|
48
|
-
| `vhost` | String | sí (validate!) | `'/'` | code-default | `:
|
|
49
|
-
| `logger` | Logger | no | `Logger.new($stdout)` INFO | code-default | `:
|
|
50
|
-
| `bunny_logger` | Logger | no | `Logger.new($stdout)` WARN | code-default | `:
|
|
51
|
-
| `automatically_recover` | Boolean | no | `true` | code-default | `:
|
|
52
|
-
| `network_recovery_interval` | Integer | no | `5` | code-default | `:
|
|
53
|
-
| `max_reconnect_attempts` | Integer/nil | no | `nil` (reintenta ∞) | code-default | `:
|
|
54
|
-
| `max_reconnect_interval` | Integer | no | `60` | code-default | `:
|
|
55
|
-
| `connection_timeout` | Integer | no (1..300) | `10` | code-default | `:
|
|
56
|
-
| `read_timeout` | Integer | no (1..300) | `30` | code-default | `:
|
|
57
|
-
| `write_timeout` | Integer | no (1..300) | `30` | code-default | `:
|
|
58
|
-
| `heartbeat` | Integer | no (0..3600) | `15` | code-default | `:
|
|
59
|
-
| `continuation_timeout` | Integer (ms) | no | `15000` | code-default | `:
|
|
60
|
-
| `channel_prefetch` | Integer | no (1..10000) | `1` | code-default | `:
|
|
61
|
-
| `rpc_timeout` | Integer | no (1..3600) | `10` | code-default | `:
|
|
62
|
-
| `health_check_interval` | Integer | no | `60` | code-default | `:
|
|
63
|
-
| `health_check_file` | String/nil | no | `nil` (desactivado) | code-default | `:
|
|
64
|
-
| `drain_idle_timeout` | Integer (s) | no (1..3600) | `5` | code-default | `:
|
|
65
|
-
| `drain_poll_interval` | Numeric (s) | no (0.01..10) | `0.1` | code-default | `:
|
|
66
|
-
| `controller_namespace` | String | no | `'BugBunny::Controllers'` | code-default | `:
|
|
67
|
-
| `log_tags` | Array | no | `[:uuid]` | code-default | `:
|
|
68
|
-
| `exchange_options` | Hash | no | `{}` | code-default | `:
|
|
69
|
-
| `queue_options` | Hash | no | `{}` | code-default | `:
|
|
70
|
-
| `consumer_middlewares` | Stack (attr_reader) | no | `Stack.new` | code-default | `:
|
|
71
|
-
| `rpc_reply_headers` | Proc/nil | no | `nil` | code-default | `:
|
|
72
|
-
| `on_rpc_reply` | Proc/nil | no | `nil` | code-default | `:
|
|
73
|
-
| `on_return` | Proc/nil | no | `nil` | code-default | `:
|
|
74
|
-
| `nack_raise` | Boolean | no | `true` | code-default | `:
|
|
75
|
-
| `return_raise` | Boolean | no | `true` | code-default | `:
|
|
52
|
+
| `host` | String | sí (validate!) | `'127.0.0.1'` | code-default | `configuration.rb:202` | no |
|
|
53
|
+
| `port` | Integer | sí (validate!, 1..65535) | `5672` | code-default | `:203` | no |
|
|
54
|
+
| `username` | String | sí (validate!) | `'guest'` | code-default | `:204` | no |
|
|
55
|
+
| `password` | String | sí (validate!) | `'guest'` | code-default | `:205` | **sí** |
|
|
56
|
+
| `vhost` | String | sí (validate!) | `'/'` | code-default | `:206` | no |
|
|
57
|
+
| `logger` | Logger | no | `Logger.new($stdout)` INFO | code-default | `:208` | no |
|
|
58
|
+
| `bunny_logger` | Logger | no | `Logger.new($stdout)` WARN | code-default | `:211` | no |
|
|
59
|
+
| `automatically_recover` | Boolean | no | `true` | code-default | `:213` | no |
|
|
60
|
+
| `network_recovery_interval` | Integer | no | `5` | code-default | `:214` | no |
|
|
61
|
+
| `max_reconnect_attempts` | Integer/nil | no | `nil` (reintenta ∞) | code-default | `:215` | no |
|
|
62
|
+
| `max_reconnect_interval` | Integer | no | `60` | code-default | `:216` | no |
|
|
63
|
+
| `connection_timeout` | Integer | no (1..300) | `10` | code-default | `:217` | no |
|
|
64
|
+
| `read_timeout` | Integer | no (1..300) | `30` | code-default | `:218` | no |
|
|
65
|
+
| `write_timeout` | Integer | no (1..300) | `30` | code-default | `:219` | no |
|
|
66
|
+
| `heartbeat` | Integer | no (0..3600) | `15` | code-default | `:220` | no |
|
|
67
|
+
| `continuation_timeout` | Integer (ms) | no | `15000` | code-default | `:221` | no |
|
|
68
|
+
| `channel_prefetch` | Integer | no (1..10000) | `1` | code-default | `:222` | no |
|
|
69
|
+
| `rpc_timeout` | Integer | no (1..3600) | `10` | code-default | `:223` | no |
|
|
70
|
+
| `health_check_interval` | Integer | no | `60` | code-default | `:224` | no |
|
|
71
|
+
| `health_check_file` | String/nil | no | `nil` (desactivado) | code-default | `:227` | no |
|
|
72
|
+
| `drain_idle_timeout` | Integer (s) | no (1..3600) | `5` | code-default | `:285` | no |
|
|
73
|
+
| `drain_poll_interval` | Numeric (s) | no (0.01..10) | `0.1` | code-default | `:286` | no |
|
|
74
|
+
| `controller_namespace` | String | no | `'BugBunny::Controllers'` | code-default | `:230` | no |
|
|
75
|
+
| `log_tags` | Array | no | `[:uuid]` | code-default | `:232` | no |
|
|
76
|
+
| `exchange_options` | Hash | no | `{}` | code-default | `:235` | no |
|
|
77
|
+
| `queue_options` | Hash | no | `{}` | code-default | `:236` | no |
|
|
78
|
+
| `consumer_middlewares` | Stack (attr_reader) | no | `Stack.new` | code-default | `:238` | no |
|
|
79
|
+
| `rpc_reply_headers` | Proc/nil | no | `nil` | code-default | `:272` | no |
|
|
80
|
+
| `on_rpc_reply` | Proc/nil | no | `nil` | code-default | `:273` | no |
|
|
81
|
+
| `on_return` | Proc/nil | no | `nil` | code-default | `:274` | no |
|
|
82
|
+
| `nack_raise` | Boolean | no | `true` | code-default | `:275` | no |
|
|
83
|
+
| `return_raise` | Boolean | no | `true` | code-default | `:276` | no |
|
|
84
|
+
| `consumer_rails_executor` | Boolean | no | `true` | code-default | `:277` | no |
|
|
76
85
|
|
|
77
86
|
> **Override por request:** `nack_raise` y `return_raise` se sobreescriben por
|
|
78
87
|
> llamada con `nack_raise:` / `return_raise:` en `Client#publish` (scope-override
|
|
@@ -93,7 +102,7 @@ El install template (`initializer.rb`) **sugiere al consumidor** wirear 4 ENV
|
|
|
93
102
|
### d. Derivaciones simples
|
|
94
103
|
|
|
95
104
|
- `url` ← `"amqp://#{username}:#{password}@#{host}:#{port}/#{vhost}"`
|
|
96
|
-
(`configuration.rb:
|
|
105
|
+
(`configuration.rb:246`).
|
|
97
106
|
- `create_connection(**options)` ← `merge_connection_options(options)` sobre la
|
|
98
107
|
config global; las options explícitas pisan los defaults (`bug_bunny.rb:88`).
|
|
99
108
|
|
|
@@ -106,11 +115,11 @@ El install template (`initializer.rb`) **sugiere al consumidor** wirear 4 ENV
|
|
|
106
115
|
|
|
107
116
|
| inyección | qué hace | ancla |
|
|
108
117
|
|---|---|---|
|
|
109
|
-
| `initializer 'bug_bunny.add_autoload_paths'` | registra `app/rabbit` en el autoloader (Zeitwerk, `eager_load: true`) si existe | `:
|
|
110
|
-
| `config.after_initialize` → `ForkTracker.after_fork` | cierra la conexión heredada en cada fork (Rails 7.1+) | `:
|
|
111
|
-
| `config.after_initialize` → `Puma.events.on_worker_boot` | mismo cierre, hook legacy Puma <5 | `:
|
|
112
|
-
| `
|
|
113
|
-
| `Spring.after_fork` | cierra conexión en preloader Spring | `:
|
|
118
|
+
| `initializer 'bug_bunny.add_autoload_paths'` | registra `app/rabbit` en el autoloader (Zeitwerk, `eager_load: true`) si existe | `:16-19` |
|
|
119
|
+
| `config.after_initialize` → `ForkTracker.after_fork` | cierra la conexión heredada en cada fork (Rails 7.1+) | `:25-27` |
|
|
120
|
+
| `config.after_initialize` → `Puma.events.on_worker_boot` | mismo cierre, hook legacy Puma <5 | `:31-35` |
|
|
121
|
+
| `config.after_initialize` → `consumer_middlewares.prepend(RailsExecutor)` | si `consumer_rails_executor` (default `true`), pone `ConsumerMiddleware::RailsExecutor` **primero** en la cadena del Consumer: cada mensaje corre dentro de `Rails.application.executor.wrap` (#70) | `:44-51` |
|
|
122
|
+
| `Spring.after_fork` | cierra conexión en preloader Spring | `:54-58` |
|
|
114
123
|
|
|
115
124
|
### f. Enriquecimiento semántico
|
|
116
125
|
|
|
@@ -128,6 +137,7 @@ del código.
|
|
|
128
137
|
| Drain (`drain_idle_timeout`/`drain_poll_interval`) | latencia | `drain_idle_timeout` muy bajo → un productor lento deja mensajes para la próxima corrida (no se pierden); muy alto → el job tarda más en terminar tras vaciar la cola | ninguno: sólo acota cuánto espera `Consumer#drain` (`consumer.rb:285`) | correr un consumidor como job que termina (#64) |
|
|
129
138
|
| Callbacks (`on_return`/`on_rpc_reply`/`rpc_reply_headers`) | extensibilidad | una excepción en `on_return` se captura pero **degrada visibilidad** (YARD `configuration.rb:157`) | corren en hilos sensibles (ver §h) | propagar trace-context / alertar unroutable |
|
|
130
139
|
| Confirms (`nack_raise`/`return_raise`) | integridad de entrega | `false` → NACK/return solo se logea, la llamada retorna `202` (modo legacy, posible pérdida silenciosa) | habilitan el raise de `PublishNacked`/`PublishUnroutable` | elegir entre fail-fast vs best-effort en publish confirmado |
|
|
140
|
+
| Executor de Rails (`consumer_rails_executor`) | aislamiento entre mensajes | `false` dentro de Rails → el estado por hilo (`CurrentAttributes`, conexión de ActiveRecord) pasa de un mensaje al siguiente, salvo que el consumidor envuelva cada mensaje por su cuenta; fuera de Rails no tiene efecto | `true` → el Railtie registra `ConsumerMiddleware::RailsExecutor` **primero** en la cadena (`railtie.rb:44-51`); en Rails ≥ 7.0, un error que escapa del mensaje además se reporta a `Rails.error` (`handled: false`), y la caché de queries de AR queda prendida durante cada mensaje | que cada mensaje empiece limpio, como un job de Sidekiq (#70) |
|
|
131
141
|
| Routing (`controller_namespace`) | seguridad | clase resuelta no subclase de `BugBunny::Controller` → el worker responde **403** + reject (guard anti-RCE, `consumer.rb:375-381`) | acota qué clases son enrutables | superficie de control de RCE |
|
|
132
142
|
| Logging (`logger`/`bunny_logger`/`log_tags`) | observabilidad | — | salida a `$stdout` por default | trazabilidad estructurada |
|
|
133
143
|
| Infra (`exchange_options`/`queue_options`) | infraestructura | options incompatibles con el broker → `PreconditionFailed` (vía `CommunicationError`) | defaults globales mergeados por recurso | declaración AMQP por default |
|
|
@@ -135,7 +145,7 @@ del código.
|
|
|
135
145
|
### g. Ramificadores intra-config
|
|
136
146
|
|
|
137
147
|
- `health_check_file = nil` (default) **desactiva** el touchfile aunque
|
|
138
|
-
`health_check_interval` siga corriendo (`configuration.rb:109-111,
|
|
148
|
+
`health_check_interval` siga corriendo (`configuration.rb:109-111,227`).
|
|
139
149
|
- `return_raise` es **inerte cuando `mandatory: false`** — sin `mandatory` el
|
|
140
150
|
broker nunca retorna, así que el flag no tiene efecto (`configuration.rb:181`).
|
|
141
151
|
- `nack_raise`/`return_raise` se sobreescriben **por request** (`Client#publish`),
|
data/docs/errors/errors.md
CHANGED
|
@@ -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:
|
|
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 |
|
data/docs/release/release.md
CHANGED
|
@@ -5,7 +5,10 @@
|
|
|
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. Incremento 2026-11-18 (release 5.4.0): versión actual; los pines de §h
|
|
11
|
+
> no se re-midieron.
|
|
9
12
|
|
|
10
13
|
## 1. Resumen
|
|
11
14
|
|
|
@@ -21,9 +24,9 @@ out-of-repo).
|
|
|
21
24
|
|
|
22
25
|
### a. Hecho verificable
|
|
23
26
|
|
|
24
|
-
- **Convención de versión:** SemVer `vX.X.X`. Actual: **5.
|
|
25
|
-
- **Source of truth:** tag remoto (`v5.
|
|
26
|
-
`lib/bug_bunny/version.rb` (`VERSION = '5.
|
|
27
|
+
- **Convención de versión:** SemVer `vX.X.X`. Actual: **5.4.0**.
|
|
28
|
+
- **Source of truth:** tag remoto (`v5.4.0`) + **triple mirror**
|
|
29
|
+
`lib/bug_bunny/version.rb` (`VERSION = '5.4.0'`) ← `bug_bunny.gemspec:7`
|
|
27
30
|
(`spec.version = BugBunny::VERSION`).
|
|
28
31
|
- **Changelog canónico:** `CHANGELOG.md` único.
|
|
29
32
|
- **Patrón de trigger:** `gema-tag` (patrón 1).
|
|
@@ -34,7 +37,7 @@ out-of-repo).
|
|
|
34
37
|
|
|
35
38
|
- **Convención:** SemVer `vX.X.X` (**con `v`** — distinto al servicio).
|
|
36
39
|
- **Source of truth:** tag remoto canónico (`git tag --sort=-v:refname` →
|
|
37
|
-
`v5.
|
|
40
|
+
`v5.4.0`).
|
|
38
41
|
- **Mirror:** `lib/bug_bunny/version.rb` (`VERSION`), leído por
|
|
39
42
|
`bug_bunny.gemspec:7` (`spec.version = BugBunny::VERSION`).
|
|
40
43
|
`required_ruby_version >= 2.6.0` (`bug_bunny.gemspec:17`).
|
|
@@ -85,11 +88,12 @@ procedimiento per-repo porque no vive acá. Una versión yankeada se anotaría e
|
|
|
85
88
|
`>= 5.1.0, < 5.2.0`, así que un minor **no entra** sin editar el `Gemfile`.
|
|
86
89
|
Consecuencia operativa: un fix publicado como **patch** lo toman con
|
|
87
90
|
`bundle update bug_bunny`; uno publicado como **minor** requiere tocar el pin
|
|
88
|
-
en cada consumidor. Estado medido el 2026-
|
|
91
|
+
en cada consumidor. Estado medido el 2026-10-16 (Gemfile y Gemfile.lock del default de cada clon del
|
|
89
92
|
workspace): `box_manager_service` en `~> 5.1.1`; `box_acs_manager`,
|
|
90
|
-
`box_cluster_manager` y `box_radius_manager` en `~> 5.1.0
|
|
91
|
-
**5.2.0
|
|
92
|
-
|
|
93
|
+
`box_cluster_manager` y `box_radius_manager` en `~> 5.1.0`, los cuatro con 5.1.1 en el lock — o sea que
|
|
94
|
+
**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
|
|
95
|
+
los consumidores (`olt_*`, `*_invoice_service`, `notification_sms_service`, `wispro_box_server`,
|
|
96
|
+
`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
|
|
93
97
|
behavior-change de `4.18.0` — `Bunny::Exception` → `CommunicationError`, o la
|
|
94
98
|
eliminación de `BugBunny::SecurityError` en `5.0.0`) obliga a los consumidores
|
|
95
99
|
a migrar; el `CHANGELOG.md` lo documenta como breaking note. **Orden de
|
data/docs/test/testing.md
CHANGED
|
@@ -1,17 +1,23 @@
|
|
|
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 `
|
|
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
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. Incremento 2026-11-18 (#72):
|
|
11
|
+
> fila `spec/rails/` (1 → 3 archivos: generador y rake tasks del Railtie), árbol de `336f1eb`. Escrito por
|
|
12
|
+
> el agente, sin verificación humana todavía.
|
|
9
13
|
|
|
10
14
|
## 1. Resumen
|
|
11
15
|
|
|
12
|
-
Suite principal **RSpec** (`spec/`,
|
|
16
|
+
Suite principal **RSpec** (`spec/`, 27 specs: 18 unit + 8 integration + 1 rails). Tarea
|
|
13
17
|
`:test` legacy de **Minitest** (`test/`, 2 archivos) fuera del default y del CI.
|
|
14
|
-
CI corre `bundle exec rake`
|
|
18
|
+
CI corre `bundle exec rake` en Ruby 3.4.4: el default corre `:spec` y `spec:rails`, cada una en
|
|
19
|
+
su proceso. `bundle exec rspec` pelado corre `spec/` sin Rails: `.rspec` excluye `spec/rails/` salvo que se lo pida
|
|
20
|
+
explícitamente (`bundle exec rspec spec/rails` la corre, en su propio proceso). Sin coverage tool
|
|
15
21
|
configurado.
|
|
16
22
|
|
|
17
23
|
## 2. Cuerpo
|
|
@@ -20,7 +26,8 @@ configurado.
|
|
|
20
26
|
|
|
21
27
|
| framework | dir | nivel | nº | propósito |
|
|
22
28
|
|---|---|---|---|---|
|
|
23
|
-
| **RSpec** `~> 3.0` | `spec/unit/` | unit |
|
|
29
|
+
| **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) |
|
|
30
|
+
| **RSpec** + `railties`/`activerecord`/`sqlite3` | `spec/rails/` | integration con Rails (sin broker) | 3 | `install_generator` (el generador no crea ni modifica `CLAUDE.md`, no lo menciona y sigue creando inicializador y `app/bug_bunny/controllers/`) · `railtie_rake_tasks` (el Railtie no define `bug_bunny:sync`) · `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) |
|
|
24
31
|
| **RSpec** | `spec/integration/` | integration | 8 | client, consumer_middleware, controller, drain, error_handling, infrastructure, publisher_confirms, resource — **requieren RabbitMQ real** (usan `BugBunny.create_connection` + pool) |
|
|
25
32
|
| **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 |
|
|
26
33
|
|
|
@@ -30,13 +37,16 @@ Sin tags declarados (`:slow`/`:js`) en la config de RSpec.
|
|
|
30
37
|
|
|
31
38
|
| objetivo | comando | qué corre |
|
|
32
39
|
|---|---|---|
|
|
33
|
-
| default / CI | `bundle exec rake` |
|
|
40
|
+
| 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']` |
|
|
41
|
+
| `spec/` sin Rails | `bundle exec rspec` | todo `spec/` menos `spec/rails/` (lo excluye `.rspec` cuando no se pide `spec/rails` explícitamente) |
|
|
34
42
|
| solo unit | `bundle exec rake spec:unit` | `spec/unit/**/*_spec.rb` |
|
|
35
43
|
| solo integration | `bundle exec rake spec:integration` | `spec/integration/**/*_spec.rb` (requiere broker) |
|
|
44
|
+
| 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` |
|
|
36
45
|
| Minitest legacy | `bundle exec rake test` | `test/**/*_test.rb` |
|
|
37
46
|
| CI | `.github/workflows/main.yml` → `bundle exec rake` | matrix Ruby `3.4.4`, `ruby/setup-ruby@v1` + `bundler-cache`, on push `main` + PR |
|
|
38
47
|
|
|
39
|
-
>
|
|
48
|
+
> Las tareas RSpec corren con `--require spec_helper` (`Rakefile`), salvo `spec:rails`, que
|
|
49
|
+
> carga su propio `spec/rails/rails_helper.rb`.
|
|
40
50
|
|
|
41
51
|
### c. Fixtures / Factories
|
|
42
52
|
|
|
@@ -185,6 +185,16 @@ module BugBunny
|
|
|
185
185
|
# `Client#publish`.
|
|
186
186
|
attr_accessor :return_raise
|
|
187
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
|
+
|
|
188
198
|
# @!endgroup
|
|
189
199
|
|
|
190
200
|
# Inicializa la configuración con valores por defecto seguros.
|
|
@@ -264,6 +274,7 @@ module BugBunny
|
|
|
264
274
|
@on_return = nil
|
|
265
275
|
@nack_raise = true
|
|
266
276
|
@return_raise = true
|
|
277
|
+
@consumer_rails_executor = true
|
|
267
278
|
end
|
|
268
279
|
|
|
269
280
|
# Defaults de {BugBunny::Consumer#drain}.
|
|
@@ -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? }
|