bug_bunny 5.0.0 → 5.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e1076566b6a3b8c25f6f00fc624c92681e8db881ffc3b8d6640da3bb7158333b
-  data.tar.gz: 2510fe871ec6f32804dba3faa7f1110408656e8cff30d2c0d537c7d0b30e1686
+  metadata.gz: 877e5f5961f53d587b2bc67e6a8c39d247b996e1272ddad076236633df65f267
+  data.tar.gz: 6928594ae30624f1dccd2841594bee4b0faed40ee0cd238a69387399559a757b
 SHA512:
-  metadata.gz: 13525491f89b99f1e1be12663f64990109e17b9da22e034ecea463a3fda5ff68abfb3ab10fdf274d43df5460b3c74eabd14e1699e2af7f8c38e608a78e22cb69
-  data.tar.gz: 9f31c6ed9fbfff650e2770f970ab94e49979f8eec8b254c212817ca410106b4f4293cc9b6cde87f382145a2483f639aabe0998134c5656b7ec6b053aebcb7c73
+  metadata.gz: fea6d7206396aae6ff2b35277e651ed944bee590f74200a392f2fb962af8757f56057b6d637434a91603d272b59b6215b459b330e98999d37f72d1c2ad6af763
+  data.tar.gz: b9d531b234ec094ab7127ea5921506d92a32e57961463904e6a62e158ce8a8e3020368ff1c6006cb30ae62a5beea942f3c004ce33e91362c910de2e87165aa6e

data/AGENTS.md

@@ -17,7 +17,7 @@ proyecto y convenciones de equipo, ver `CLAUDE.md`. Para la entrada humana, ver
 | 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 |
 | Configuración | `docs/config/configuracion.md` | completo (estructura + enrich §f/g/h) | opciones de `Configuration`, defaults, failure-mode/threading, inyecciones del `Railtie`, ENV sugeridas |
 | Dependencias consumidas | `docs/consumed/rabbitmq.md` | completo (estructura + enrich §c/e) | qué consume del broker RabbitMQ vía `bunny`, mapeo error-Bunny→excepción, retry/degradación |
-| Test | `docs/test/test.md` | completo (estructura + enrich §e-h) | suites RSpec/Minitest, CI, contract-assessment, link a incidentes (#49/#52) |
+| Test | `docs/test/testing.md` | completo (estructura + enrich §e-h) | suites RSpec/Minitest, CI, contract-assessment, link a incidentes (#49/#52) |
 | Release | `docs/release/release.md` | completo | patrón gema-tag, versionado, publish a RubyGems |
 | Datos | — | n/a | gema sin DB |
 | Operaciones / Interfaz / Topología | — | dev-structure F2 no implementado | contrato embebido en `README.md`/`skill/SKILL.md` (interim RFC-008 §2) |

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [5.1.0] - 2026-07-22
+
+### Nuevas funcionalidades
+- **Hook `extra_top_level_params` en `Resource#save`:** una subclase puede sobrescribirlo (default `{}`) para mergear datos TOP-LEVEL hermanos del recurso en el body del `save` —fuera del wrapper `param_key`— sin que sean atributos del recurso ni se persistan en el modelo. Caso de uso: un dato de transporte (p. ej. una credencial) que el servidor lee como `params[:x]`. No-breaking (el default `{}` deja el body idéntico para los recursos que no lo sobrescriben). — @Pslp
+
+### Documentación
+- `docs/test/` incrementado (spec `extra_top_level_params`, conteos 16 unit / 23 total) y renombrado a `docs/test/testing.md` (filename canónico RFC-013). Hook documentado en el contrato interino `skill/references/resource.md`. — @Pslp
+
 ## [5.0.0] - 2026-07-01
 
 > **BREAKING.** Se elimina la constante pública `BugBunny::SecurityError`. Aunque la excepción nunca se *levantaba*, su **ausencia rompe en evaluación**: un `rescue BugBunny::SecurityError` en un consumidor resuelve la constante cuando *cualquier* excepción entra a ese bloque → `NameError` que enmascara la excepción original. Por eso es breaking real, no inerte.

data/docs/test/{test.md → testing.md}

@@ -1,14 +1,14 @@
 # Test — bug_bunny
 
 > meta: artefacto test · RFC-013 · generado `arch-structure` (§a-§d) +
-> `arch-enrich` (§e-§h) · anclado a `24ea397`, `Rakefile`, `bug_bunny.gemspec`,
+> `arch-enrich` (§e-§h) · anclado a `7bf1da7`, `Rakefile`, `bug_bunny.gemspec`,
 > `spec/spec_helper.rb`, `spec/support/integration_helper.rb`,
-> `.github/workflows/main.yml`, `CHANGELOG.md` · fecha 2026-06-30 · cobertura:
+> `.github/workflows/main.yml`, `CHANGELOG.md` · fecha 2026-07-22 · cobertura:
 > §a-§d (estructura) + §e-§h (enrich, anclado a specs/CHANGELOG) completas.
 
 ## 1. Resumen
 
-Suite principal **RSpec** (`spec/`, 22 specs: 15 unit + 7 integration). Tarea
+Suite principal **RSpec** (`spec/`, 23 specs: 16 unit + 7 integration). Tarea
 `:test` legacy de **Minitest** (`test/`, 2 archivos) fuera del default y del CI.
 CI corre `bundle exec rake` (= `:spec`) en Ruby 3.4.4. Sin coverage tool
 configurado.
@@ -19,7 +19,7 @@ configurado.
 
 | framework | dir | nivel | nº | propósito |
 |---|---|---|---|---|
-| **RSpec** `~> 3.0` | `spec/unit/` | unit | 15 | client/session pool, configuration, consumer, producer, controller, raise_error, remote_error, request, route, observability, otel, resource, middleware |
+| **RSpec** `~> 3.0` | `spec/unit/` | unit | 16 | client/session pool, configuration, consumer, producer, controller, raise_error, remote_error, request, route, observability, otel, resource, middleware, `extra_top_level_params` (hook de params hermanos en `Resource#save`) |
 | **RSpec** | `spec/integration/` | integration | 7 | client, consumer_middleware, controller, error_handling, infrastructure, publisher_confirms, resource — **requieren RabbitMQ real** (usan `BugBunny.create_connection` + pool) |
 | **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 |
 
@@ -60,7 +60,7 @@ umbral de coverage declarado.
 - **Integration specs no corren en CI:** `main.yml` no declara servicio RabbitMQ;
   las 7 integration specs **se skipean** vía `rabbitmq_available?`
   (`spec/support/integration_helper.rb:14`, ver `publisher_confirms_spec.rb:10`).
-  En CI solo se ejercitan las **15 unit specs** → el contrato AMQP real (publish/
+  En CI solo se ejercitan las **16 unit specs** → el contrato AMQP real (publish/
   consume/confirms contra broker) **no se valida en pipeline**, solo localmente
   con broker. Gap relevante.
 - **Sin medición de cobertura:** no hay SimpleCov ni umbral → la cobertura no está

data/lib/bug_bunny/resource.rb

@@ -440,7 +440,7 @@ module BugBunny
         rk = calculate_routing_key(id)
         flat_payload = changes_to_send
         key = self.class.param_key
-        wrapped_payload = { key => flat_payload }
+        wrapped_payload = { key => flat_payload }.merge(extra_top_level_params)
 
         path = is_new ? self.class.resource_name : "#{self.class.resource_name}/#{id}"
         method = is_new ? :post : :put
@@ -467,6 +467,20 @@ module BugBunny
       false
     end
 
+    # Params top-level extra a incluir en el body del `save`, JUNTO al recurso
+    # envuelto en `param_key` (no dentro de él). Default: ninguno.
+    #
+    # Las subclases lo sobrescriben para enviar datos HERMANOS del recurso que no
+    # forman parte de sus atributos ni deben persistir en el modelo — p. ej. una
+    # credencial de transporte que el servidor lee como `params[:x]` y que no se
+    # serializa dentro del recurso. Se mergea sobre `{ param_key => attrs }`, así
+    # que no debe usar `param_key` como clave (colisionaría con el recurso).
+    #
+    # @return [Hash]
+    def extra_top_level_params
+      {}
+    end
+
     # Elimina el recurso del servidor remoto (DELETE).
     #
     # @return [Boolean]

data/lib/bug_bunny/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BugBunny
-  VERSION = '5.0.0'
+  VERSION = '5.1.0'
 end

data/skill/references/resource.md

@@ -65,6 +65,24 @@ order.errors                             # ActiveModel::Errors
 - **Existente** (`persisted? == true`): Envía PUT solo con atributos cambiados (`changes_to_send`).
 - Captura `BugBunny::UnprocessableEntity` (422) y carga `resource.errors`. Retorna `false`.
 
+### Params top-level hermanos: `extra_top_level_params`
+
+Por default `save` envía el body `{ param_key => attrs }`. Una subclase puede sobrescribir `extra_top_level_params` (default `{}`) para mergear datos **top-level hermanos** del recurso —fuera del wrapper `param_key`— sin que sean atributos del recurso ni se persistan en el modelo. Caso de uso: un dato de transporte (p. ej. una credencial) que el servidor lee como `params[:x]`.
+
+```ruby
+class Service < BugBunny::Resource
+  self.param_key = 'service'
+  attr_accessor :registry_auth   # dato transiente, NO atributo del recurso
+
+  def extra_top_level_params
+    registry_auth ? { registry_auth: registry_auth } : {}
+  end
+end
+# save envía: { 'service' => { ...attrs }, registry_auth: '...' }
+```
+
+No debe usar `param_key` como clave (colisionaría con el wrapper del recurso).
+
 ## Contexto Dinámico (.with)
 
 ### Forma de bloque (recomendada)

data/spec/unit/extra_top_level_params_spec.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+# Hook `extra_top_level_params`: permite a una subclase mandar params HERMANOS del
+# recurso en el body del `save` (top-level, junto al `param_key`), sin que formen
+# parte de los atributos del recurso ni se persistan en el modelo. Caso de uso:
+# una credencial de transporte que el servidor lee como `params[:x]`.
+module ExtraTopLevelParamsSpec
+  # Recurso sin override: usa el hook por default (no manda extras).
+  class Plain < BugBunny::Resource
+    self.resource_name = 'widget'
+    self.param_key     = 'widget'
+    self.exchange      = 'etlp_ex'
+    self.exchange_type = 'direct'
+    attribute :name, :string
+  end
+
+  # Recurso que sobrescribe el hook para mandar un sibling transiente (no atributo).
+  class WithSibling < BugBunny::Resource
+    self.resource_name = 'service'
+    self.param_key     = 'service'
+    self.exchange      = 'etlp_ex'
+    self.exchange_type = 'direct'
+    attribute :name, :string
+
+    attr_accessor :registry_auth
+
+    def extra_top_level_params
+      registry_auth ? { registry_auth: registry_auth } : {}
+    end
+  end
+end
+
+RSpec.describe 'BugBunny::Resource#extra_top_level_params' do
+  let(:client) { instance_double(BugBunny::Client) }
+
+  before do
+    allow(client).to receive(:request) do |_path, **args|
+      @sent_body = args[:body]
+      { 'body' => {} }
+    end
+  end
+
+  def save_with_stub(resource)
+    allow(resource).to receive(:bug_bunny_client).and_return(client)
+    resource.save
+  end
+
+  it 'default: el body solo envuelve el recurso en param_key (sin extras)' do
+    save_with_stub(ExtraTopLevelParamsSpec::Plain.new(name: 'w'))
+
+    expect(@sent_body.keys).to eq(['widget'])
+  end
+
+  it 'override: agrega el sibling top-level JUNTO al recurso envuelto, no adentro' do
+    resource = ExtraTopLevelParamsSpec::WithSibling.new(name: 's').tap { |r| r.registry_auth = 'b64cred' }
+
+    save_with_stub(resource)
+
+    expect(@sent_body[:registry_auth]).to eq('b64cred')
+    expect(@sent_body['service']).not_to have_key('registry_auth')
+  end
+
+  it 'override sin valor: no agrega el sibling (hook devuelve {})' do
+    save_with_stub(ExtraTopLevelParamsSpec::WithSibling.new(name: 's'))
+
+    expect(@sent_body.keys).to eq(['service'])
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bug_bunny
 version: !ruby/object:Gem::Version
-  version: 5.0.0
+  version: 5.1.0
 platform: ruby
 authors:
 - gabix
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-01 00:00:00.000000000 Z
+date: 2026-07-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bunny
@@ -240,7 +240,7 @@ files:
 - docs/errors/errors.md
 - docs/glossary/glossary.md
 - docs/release/release.md
-- docs/test/test.md
+- docs/test/testing.md
 - initializer_example.rb
 - lib/bug_bunny.rb
 - lib/bug_bunny/client.rb
@@ -294,6 +294,7 @@ files:
 - spec/unit/consumer_middleware_spec.rb
 - spec/unit/consumer_spec.rb
 - spec/unit/controller_after_action_spec.rb
+- spec/unit/extra_top_level_params_spec.rb
 - spec/unit/observability_spec.rb
 - spec/unit/otel_spec.rb
 - spec/unit/producer_spec.rb
@@ -313,7 +314,7 @@ metadata:
   homepage_uri: https://github.com/gedera/bug_bunny
   source_code_uri: https://github.com/gedera/bug_bunny
   changelog_uri: https://github.com/gedera/bug_bunny/blob/main/CHANGELOG.md
-  documentation_uri: https://github.com/gedera/bug_bunny/blob/v5.0.0/skill
+  documentation_uri: https://github.com/gedera/bug_bunny/blob/v5.1.0/skill
 post_install_message:
 rdoc_options: []
 require_paths: