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 CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 6ac482578cfbb87414309cc03502be5f11c4ee4b0e799338bfeb9bfcf65488f5
4
- data.tar.gz: a4a9e64ac077bd6564790a5de762c804d38c65623f2c7cbc839217bb8f98bd25
3
+ metadata.gz: d8ca8ec1c80982fc9a195a414e2af1039994e66ca1c10d33b3de36a3bc5cdc6b
4
+ data.tar.gz: 5b42f7076a1330857b18395146c6a423d8abdf8f52b53f06081adbc7e915995a
5
5
  SHA512:
6
- metadata.gz: e33cbdca7040793e46116fdf744d3f89bdd71a4b278a12aaa85f3845c6aba1ea86dbfded00c3108b60e04759dea07f52a7765d430fcc3bbc3ff2090b01f38c9a
7
- data.tar.gz: be41989086784220c62b3e9ee4909f064956c3bf7dcaade12473d039c16743732a75f1d60844ffc22fcbe0afb36c518e14dbb74713cc0ef7007f9658d2be13d1
6
+ metadata.gz: 2bdac4c3895b7fdb2b092cb37eb96be256434a80d097226d65a8b471f16a1a40c61fac3eac46b5175e4341abcd476a53e7dca84b5244250123aa2d252eb656f5
7
+ data.tar.gz: 4ceb135c73aee74d9df64828d46a420f1b3463f162bfab2fcb293a361e88222366faaac211c96bf8965448f4972a7c015d58797a8f9a113e7dc555827a2c3209
data/.rspec ADDED
@@ -0,0 +1,2 @@
1
+ <%# spec/rails/ bootea Rails y corre en su propio proceso: se excluye salvo que se pida explícitamente. %>
2
+ <%= '--exclude-pattern spec/rails/**/*_spec.rb' unless ARGV.any? { |arg| arg.start_with?('spec/rails') } %>
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 (7 flujos) | secuencias de publish/RPC/consume/confirms, contrato de error-wrapping |
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 rspec`, YARD incremental (`bundle exec yard stats --list-undoc`).
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.2.0`.
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 — 6 flujos (backfill on-demand) |
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 — 16 unit / 7 integration |
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
- task default: :spec
35
+ # Las dos suites, cada una en su proceso: es lo que corren `quality-code` y `gem-release`.
36
+ task default: [:spec, 'spec:rails']
@@ -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 `35b075a` (squash de #65 en `main`) · cobertura: completa (7 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**
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 `35b075a`. Acreta incremental en cada PR que toque un flujo (default RFC-007). Ausencia futura ≠ inexistencia.
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 `35b075a` (squash de #65 en `main`),
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`):** 32 (31 `attr_accessor` + 1 `attr_reader`; medido
26
- 2026-09-28 — el `29` anterior ya estaba desfasado del código antes de #64).
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:** 32 (todas; defaults en `initialize`/`init_callback_defaults`/`init_drain_defaults`).
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:192` | no |
45
- | `port` | Integer | sí (validate!, 1..65535) | `5672` | code-default | `:193` | no |
46
- | `username` | String | sí (validate!) | `'guest'` | code-default | `:194` | no |
47
- | `password` | String | sí (validate!) | `'guest'` | code-default | `:195` | **sí** |
48
- | `vhost` | String | sí (validate!) | `'/'` | code-default | `:196` | no |
49
- | `logger` | Logger | no | `Logger.new($stdout)` INFO | code-default | `:198` | no |
50
- | `bunny_logger` | Logger | no | `Logger.new($stdout)` WARN | code-default | `:201` | no |
51
- | `automatically_recover` | Boolean | no | `true` | code-default | `:203` | no |
52
- | `network_recovery_interval` | Integer | no | `5` | code-default | `:204` | no |
53
- | `max_reconnect_attempts` | Integer/nil | no | `nil` (reintenta ∞) | code-default | `:205` | no |
54
- | `max_reconnect_interval` | Integer | no | `60` | code-default | `:206` | no |
55
- | `connection_timeout` | Integer | no (1..300) | `10` | code-default | `:207` | no |
56
- | `read_timeout` | Integer | no (1..300) | `30` | code-default | `:208` | no |
57
- | `write_timeout` | Integer | no (1..300) | `30` | code-default | `:209` | no |
58
- | `heartbeat` | Integer | no (0..3600) | `15` | code-default | `:210` | no |
59
- | `continuation_timeout` | Integer (ms) | no | `15000` | code-default | `:211` | no |
60
- | `channel_prefetch` | Integer | no (1..10000) | `1` | code-default | `:212` | no |
61
- | `rpc_timeout` | Integer | no (1..3600) | `10` | code-default | `:213` | no |
62
- | `health_check_interval` | Integer | no | `60` | code-default | `:214` | no |
63
- | `health_check_file` | String/nil | no | `nil` (desactivado) | code-default | `:217` | no |
64
- | `drain_idle_timeout` | Integer (s) | no (1..3600) | `5` | code-default | `:274` | no |
65
- | `drain_poll_interval` | Numeric (s) | no (0.01..10) | `0.1` | code-default | `:275` | no |
66
- | `controller_namespace` | String | no | `'BugBunny::Controllers'` | code-default | `:220` | no |
67
- | `log_tags` | Array | no | `[:uuid]` | code-default | `:222` | no |
68
- | `exchange_options` | Hash | no | `{}` | code-default | `:225` | no |
69
- | `queue_options` | Hash | no | `{}` | code-default | `:226` | no |
70
- | `consumer_middlewares` | Stack (attr_reader) | no | `Stack.new` | code-default | `:228` | no |
71
- | `rpc_reply_headers` | Proc/nil | no | `nil` | code-default | `:262` | no |
72
- | `on_rpc_reply` | Proc/nil | no | `nil` | code-default | `:263` | no |
73
- | `on_return` | Proc/nil | no | `nil` | code-default | `:264` | no |
74
- | `nack_raise` | Boolean | no | `true` | code-default | `:265` | no |
75
- | `return_raise` | Boolean | no | `true` | code-default | `:266` | no |
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:236`).
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 | `:15-18` |
110
- | `config.after_initialize` → `ForkTracker.after_fork` | cierra la conexión heredada en cada fork (Rails 7.1+) | `:24-26` |
111
- | `config.after_initialize` → `Puma.events.on_worker_boot` | mismo cierre, hook legacy Puma <5 | `:30-34` |
112
- | `rake_tasks` | carga `tasks/bug_bunny.rake` (`bug_bunny:sync`) | `:38-40` |
113
- | `Spring.after_fork` | cierra conexión en preloader Spring | `:43-47` |
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,217`).
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`),
@@ -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:282,289,297` — 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 |
@@ -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.2.0**.
25
- - **Source of truth:** tag remoto (`v5.2.0`) + **triple mirror**
26
- `lib/bug_bunny/version.rb` (`VERSION = '5.2.0'`) ← `bug_bunny.gemspec:7`
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.2.0`).
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-09-29 (Gemfiles de los clones del
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` — o sea que
91
- **5.2.0 no le entra a ninguno** sin tocar el pin. *(El estado anterior decía
92
- `box_acs_manager`/`box_cluster_manager` en `~> 4.19.0`: ya no es así.)* Un cambio de contrato del gem (ej. el
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 `35b075a` (squash de #65 en `main`; el ancla anterior `7bf1da7` no era ancestro de `main`), `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
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/`, 25 specs: 17 unit + 8 integration). Tarea
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` (= `:spec`) en Ruby 3.4.4. Sin coverage tool
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 | 17 | 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`) |
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` | tarea `:spec` (toda la suite RSpec) — `Rakefile:` `task default: :spec` |
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
- > Todas las tareas RSpec corren con `--require spec_helper` (`Rakefile`).
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? }