bug_bunny 4.16.0 → 4.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 67e58763b6f088c44e17121922ecb618c9ccef8738096d534c578eea021c5f94
-  data.tar.gz: 47fe7485dd056e9ffb8a7e5268b97e4d0173e0441984506b5528f5c43643da7a
+  metadata.gz: ec5013f4d782766d388826265255b008a9c17119b15acef95a05fcb01a9722d5
+  data.tar.gz: 0cd930d1d4c982a0ba9bf73e9562504d0e776c88c760e427dc440a1399b57a13
 SHA512:
-  metadata.gz: f0a5927c4a4a450b414ee38ffbc25a0a97a80b2678d32a19d524a51367572f7b5e2935e29a81bf9afbdd2cfb0b634e9b60a322b828ff14ba0f79e60982148723
-  data.tar.gz: e66726447226ceb96f2d3b81dd759209fd8e54e7ea67bb85870cc805e44747e81f8121a821fd7a6fa65435ae3ba95e3cd62631ef0687fa0543f29848e21f4682
+  metadata.gz: 800c22370b7e39812cc1d90ca74db9ea4736e4354e4061d39a0e0e9d5fbb7fa5ff05c56474f61056a7fe072144339c48d725f040c34c16ba7f0805a314881d66
+  data.tar.gz: 921e0359f5426db49beaf327e67885568313282c3972e9bc2e9d7f88e28fdad032f3258ab73e4cca16f9b3f70cdbf5f42311e3d4f910e4430494ebb4ea8e05a8

data/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## [4.17.0] - 2026-05-13
+
+### Nuevas funcionalidades
+- **`Client::REQUEST_ATTRS` extendido con metadata AMQP estándar (#45):** Los siguientes atributos del Request ahora pueden pasarse como kwargs directos en `client.publish` / `client.request` sin necesidad del block API:
+  - `persistent` (Boolean) — `delivery_mode: 2` AMQP. Critical: por default es `false`; `confirmed: true` **NO** lo implica.
+  - `correlation_id` (String) — Tracing explícito (sobreescribe el auto-asignado por RPC y `return_raise`).
+  - `priority` (Integer 0-255).
+  - `app_id` (String).
+  - `content_type` (String, default `'application/json'`).
+  - `content_encoding` (String).
+  - `expiration` (String, TTL en ms).
+
+  ```ruby
+  # Antes (4.16): requería block API
+  client.publish('evt', exchange: 'x', confirmed: true) do |req|
+    req.persistent = true
+    req.correlation_id = 'cid-123'
+  end
+
+  # Ahora (4.17): kwargs directos
+  client.publish('evt', exchange: 'x', confirmed: true,
+                 persistent: true, correlation_id: 'cid-123')
+  ```
+
+  El block API sigue funcionando para overrides puntuales o para atributos no expuestos (`timestamp`, `type`, `reply_to`).
+
+### Correcciones
+- **`apply_args` usa `args.key?` en lugar de truthy check:** Permite pasar valores falsy explícitos (ej. `persistent: false`, `priority: 0`) que antes se filtraban silenciosamente como si no se hubieran pasado.
+
+### Documentación (motivado por #45 — adopción real en sequre/box_radius_manager#18)
+- README + SKILL.md cubren cuatro gotchas detectados solo en integration tests:
+  1. `url` es positional, no kwarg `:path`. Splatear un hash con `path:` rompe.
+  2. `confirmed: true` no implica `persistent: true` — son flags ortogonales.
+  3. Default `exchange_options` es `{ durable: false }` — publishers a exchange compartido deben pasar `exchange_options: { durable: true }` explícito.
+  4. `instance_double` no detecta arity mismatch con splat de kwargs — recomendación de smoke test integration para cada publisher nuevo.
+- Nueva sección "Production publisher recipe" en README y receta canónica en SKILL.md con la combinación recomendada para auditoría/billing/accounting.
+- `skill/references/client-middleware.md` con tabla completa de kwargs de Request actualizada.
+
 ## [4.16.0] - 2026-05-13
 
 ### Cambios de comportamiento (semi-breaking)

data/README.md

@@ -210,6 +210,73 @@ client.publish('events', body: { type: 'user.signed_in', user_id: 42 })
 client.request('users', method: :get, params: { role: 'admin', page: 2 })
 ```
 
+### Gotchas
+
+**URL is positional, not a kwarg.** The first argument of `client.request` / `client.publish` is positional. There is **no** `path:` kwarg, splatting a hash with `path:` will fail silently or raise `ArgumentError`:
+
+```ruby
+args = { exchange: 'ingest.x', body: payload }
+client.publish(**args)              # ❌ ArgumentError: wrong number of arguments
+client.publish('event.name', **args) # ✅
+```
+
+**Block runs after kwargs.** Keyword args are applied first; the block (if given) can override them. Use kwargs for the common case and block for atypical setup:
+
+```ruby
+client.publish('evt', exchange: 'x', persistent: true) do |req|
+  req.timestamp = some_past_time   # only via block — not in REQUEST_ATTRS
+end
+```
+
+### Production publisher recipe
+
+Defaults aimed at sane microservices — declare durable exchanges, persistent messages, confirmed delivery with mandatory routing, explicit correlation id:
+
+```ruby
+client.publish('acct.start',
+               exchange:         'ingest.radius',
+               exchange_type:    :topic,
+               exchange_options: { durable: true },   # match consumer-declared exchange
+               body:             payload,
+               confirmed:        true,
+               mandatory:        true,                # raise PublishUnroutable if no binding
+               persistent:       true,                # delivery_mode: 2 — survives broker restart
+               correlation_id:   SecureRandom.uuid,
+               app_id:           'radius_manager')
+```
+
+| AMQP property | Kwarg | Reason it matters for critical publishers |
+|---|---|---|
+| `delivery_mode` | `persistent: true` | Without it, the message lives only in broker RAM (lost on restart). Default `false`. |
+| `confirmation` | `confirmed: true` | Block until the broker acks. Without it, `client.publish` returns 202 before the broker sees the message. |
+| `mandatory` | `mandatory: true` | Catches misrouted publishes. Combined with `return_raise` (default `true`), raises `PublishUnroutable` instead of silently dropping. |
+| `exchange durable` | `exchange_options: { durable: true }` | Match the exchange definition that consumers declare. Mismatch raises `Bunny::PreconditionFailed`. |
+| `correlation_id` | `correlation_id:` | Tracing. Auto-generated when missing for RPC and for `confirmed + mandatory + return_raise`, but explicit is preferred. |
+
+### Testing publishers
+
+Mocks of `Client` (via `instance_double`) **do not catch arity mismatches** when the caller does splat (`**args`). Signature errors like passing `path:` as kwarg or unknown keys won't surface in unit tests with mocks. **Add a smoke integration test** for new publishers — declare an exclusive queue, bind to the exchange, publish, `queue.pop`, assert `correlation_id`, `headers`, `routing_key`, `delivery_mode`:
+
+```ruby
+RSpec.describe 'MyPublisher', :integration do
+  it 'publishes with correct AMQP metadata' do
+    conn = BugBunny.create_connection
+    ch   = conn.create_channel
+    x    = ch.topic('ingest.radius', durable: true)
+    q    = ch.queue('', exclusive: true).bind(x, routing_key: 'acct.#')
+
+    MyPublisher.call(payload)
+
+    _delivery, props, body = q.pop(manual_ack: false)
+    expect(props.correlation_id).not_to be_nil
+    expect(props.delivery_mode).to eq(2)         # persistent
+    expect(JSON.parse(body)).to include(...)
+  ensure
+    conn&.close
+  end
+end
+```
+
 ### Publisher Confirms (delivery-critical events)
 
 For events where you need a delivery guarantee from the broker (auditing, billing, accounting) without the cost of a full RPC, use `publish` with `confirmed: true`. The call blocks until the broker acknowledges receipt:

data/lib/bug_bunny/client.rb

@@ -29,9 +29,17 @@ module BugBunny
     attr_accessor :delivery_mode
 
     # Argumentos del cliente que se mapean 1:1 a setters del Request.
+    #
+    # Incluye opciones de enrutamiento (`delivery_mode`, `method`, `body`, `exchange`,
+    # `exchange_type`, `routing_key`, `timeout`, `params`), de infraestructura
+    # (`exchange_options`, `queue_options`) y de metadata AMQP estándar
+    # (`persistent`, `correlation_id`, `priority`, `app_id`, `content_type`,
+    # `content_encoding`, `expiration`). Lo que no esté acá debe setearse via
+    # block API (`do |req| ... end`).
     REQUEST_ATTRS = %i[
       delivery_mode method body exchange exchange_type routing_key
       timeout exchange_options queue_options params
+      persistent correlation_id priority app_id content_type content_encoding expiration
     ].freeze
 
     # Inicializa un nuevo cliente.
@@ -64,7 +72,8 @@ module BugBunny
     #
     # Envía un mensaje y bloquea la ejecución del hilo actual hasta recibir respuesta.
     #
-    # @param url [String] La ruta del recurso (ej: 'users/1').
+    # @param url [String] La ruta del recurso (ej: 'users/1'). **Argumento posicional** —
+    #   no existe el kwarg `:path`. Splatear un hash con `path:` falla silencioso.
     # @param args [Hash] Opciones de configuración.
     # @option args [Symbol] :method El verbo HTTP (:get, :post, :put, :delete). Default: :get.
     # @option args [Object] :body El cuerpo del mensaje.
@@ -72,7 +81,18 @@ module BugBunny
     # @option args [Integer] :timeout Tiempo máximo de espera.
     # @option args [Hash] :exchange_options Opciones específicas para la declaración del Exchange.
     # @option args [Hash] :queue_options Opciones específicas para la declaración de la Cola.
-    # @yield [req] Bloque para configurar el objeto Request directamente.
+    # @option args [Boolean] :persistent Si `true`, `delivery_mode: 2` (mensaje persiste en disco
+    #   del broker). Default `false`. Útil para mensajes críticos sobre queues durables.
+    # @option args [String] :correlation_id ID de correlación AMQP. Útil para tracing custom.
+    #   Si no se setea, `Producer#rpc` y `Producer#confirmed` (con return_raise) auto-asignan UUID.
+    # @option args [Integer] :priority Prioridad del mensaje (0-255). Requiere queue declarada con
+    #   `x-max-priority` para que el broker la respete.
+    # @option args [String] :app_id Identificador del publisher.
+    # @option args [String] :content_type MIME type. Default `'application/json'`.
+    # @option args [String] :content_encoding Encoding del payload (ej: 'gzip').
+    # @option args [String] :expiration TTL del mensaje en ms (formato AMQP).
+    # @yield [req] Bloque para configurar el objeto Request directamente. Necesario para
+    #   atributos no mapeados como kwarg (ej: `req.timestamp = ...`).
     # @return [Hash] La respuesta del servidor.
     def request(url, **args)
       send(url, **args) do |req|
@@ -87,7 +107,8 @@ module BugBunny
     # que el broker confirme la recepción del mensaje. Útil para eventos críticos (auditoría,
     # billing) donde se requiere garantía de entrega sin el overhead de un RPC completo.
     #
-    # @param url [String] La ruta del evento/recurso.
+    # @param url [String] La ruta del evento/recurso. **Argumento posicional** — no
+    #   existe el kwarg `:path`. Splatear un hash con `path:` falla silencioso.
     # @param args [Hash] Mismas opciones que {#request}, excepto `:timeout`. Adicionales:
     # @option args [Boolean] :confirmed Si `true`, espera `wait_for_confirms` del broker.
     # @option args [Boolean] :mandatory Si `true`, el broker retorna el mensaje si no es ruteable.
@@ -158,12 +179,16 @@ module BugBunny
 
     # Mapea los argumentos generales (no específicos de Publisher Confirms) sobre el Request.
     #
+    # Usa `args.key?` en lugar de truthy check para que `persistent: false`,
+    # `priority: 0` u otros valores falsy explícitos del caller sean honrados
+    # (no se filtran como si no hubieran sido pasados).
+    #
     # @param req [BugBunny::Request]
     # @param args [Hash]
     # @return [void]
     def apply_args(req, args)
       REQUEST_ATTRS.each do |key|
-        req.public_send("#{key}=", args[key]) if args[key]
+        req.public_send("#{key}=", args[key]) if args.key?(key)
       end
       req.headers.merge!(args[:headers]) if args[:headers]
     end

data/lib/bug_bunny/version.rb

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

data/skill/SKILL.md

@@ -245,6 +245,21 @@ client.publish('acct.start', exchange: 'acct_x', body: payload,
 # → { 'status' => 202, 'body' => nil }   # broker ACK confirmado
 ```
 
+**Receta canónica de publisher productivo (auditoría / billing / accounting):**
+```ruby
+client.publish('acct.start',
+               exchange:         'ingest.radius',
+               exchange_type:    :topic,
+               exchange_options: { durable: true },    # matchear declaración del consumer
+               body:             payload,
+               confirmed:        true,                 # broker ACK síncrono
+               mandatory:        true,                 # raise PublishUnroutable si no hay binding
+               persistent:       true,                 # delivery_mode: 2 — sobrevive restart
+               correlation_id:   SecureRandom.uuid,    # tracing explícito
+               app_id:           'radius_manager')
+```
+A partir de 4.17, `persistent`, `correlation_id`, `priority`, `app_id`, `content_type`, `content_encoding` y `expiration` están en `Client::REQUEST_ATTRS` y se aceptan como kwargs. El block API sigue funcionando para overrides puntuales o para atributos no expuestos (`timestamp`, `type`).
+
 **Dos señales del broker, dos excepciones simétricas:**
 
 | Señal | Default | Excepción | Campos |
@@ -311,6 +326,29 @@ No guardar el resultado de `Order.with(...)` en una variable para múltiples lla
 ### Registrar middleware durante call()
 No registrar consumer middlewares durante la ejecución de `call()`. El stack toma un snapshot al inicio; los registros concurrentes no afectan la ejecución actual.
 
+### Pasar `path:` como kwarg a `Client#publish` / `#request`
+El primer argumento es **posicional** (`url`). No hay kwarg `:path`. Splatear un hash que tenga `path:` falla con `ArgumentError: wrong number of arguments`. Construir args sin path y pasar la URL aparte:
+```ruby
+args = { exchange: 'x', body: payload }
+client.publish('event.name', **args)   # ✅
+client.publish(**args.merge(path: 'event.name'))  # ❌
+```
+
+### Asumir que `confirmed: true` implica persistencia
+`confirmed: true` solo activa Publisher Confirms (broker ACK síncrono). **NO** setea `delivery_mode: 2`. El default de `Request#persistent` es `false` — el mensaje vive en RAM del broker y se pierde si reinicia. Para eventos críticos sobre queue durable hay que pasar `persistent: true` (a partir de 4.17) o setearlo via block. Tabla de decisión:
+
+| Necesitás | Pasar |
+|---|---|
+| Broker confirma recepción | `confirmed: true` |
+| Mensaje sobrevive restart | `persistent: true` (requiere queue `durable: true`) |
+| Raise si no rutea | `mandatory: true` (+ `return_raise: true` default) |
+
+### Olvidar `exchange_options: { durable: true }` en publishers a exchange compartido
+`DEFAULT_EXCHANGE_OPTIONS = { durable: false, auto_delete: false }`. Si un consumer previamente declaró el exchange como durable (caso normal en producción), un publisher que use el default va a recibir `Bunny::PreconditionFailed - inequivalent arg 'durable'` al re-declarar. Solución: pasar `exchange_options: { durable: true }` en el publisher, o setear global `BugBunny.configure { |c| c.exchange_options = { durable: true } }`.
+
+### Confiar en `instance_double(BugBunny::Client)` para detectar errores de signature
+Limitación de RSpec: `instance_double` valida que el método exista pero **no** valida arity estricta cuando el caller hace `**args` splat. Tests con mocks pasan, integration con broker real rompe. Mitigación: para cada publisher nuevo, sumar un smoke spec `:integration` que declare queue exclusiva con binding, publique, haga `queue.pop`, y verifique `correlation_id`, `delivery_mode`, `headers`, `routing_key`.
+
 ---
 
 ## Errores Comunes

data/skill/references/client-middleware.md

@@ -47,6 +47,18 @@ end
 | `mandatory` | Boolean | `false` | Pide al broker retornar el mensaje si no es ruteable. Solo útil con `confirmed: true`. |
 | `confirm_timeout` | Float | `nil` | Segundos máximos a esperar el ACK. `nil` = espera indefinida. Excedido → `BugBunny::RequestTimeout`. |
 | `nack_raise` | Boolean | `nil` | Override per-request de `config.nack_raise`. `nil` = usa flag global. |
+| `return_raise` | Boolean | `nil` | Override per-request de `config.return_raise`. Requiere `confirmed: true` y `mandatory: true`. |
+| `persistent` | Boolean | `false` | `delivery_mode: 2` AMQP. Mensaje sobrevive restart del broker. Requiere queue durable. |
+| `correlation_id` | String | nil | ID de correlación AMQP. Auto-asignado UUID en RPC y en `confirmed + mandatory + return_raise`. |
+| `priority` | Integer | nil | Prioridad 0-255. Requiere queue con `x-max-priority`. |
+| `app_id` | String | nil | Identificador del publisher (AMQP `app-id`). |
+| `content_type` | String | `'application/json'` | MIME type del payload. |
+| `content_encoding` | String | nil | Encoding del payload (`'gzip'`, `'deflate'`, etc.). |
+| `expiration` | String | nil | TTL del mensaje en ms (formato AMQP). |
+
+**Gotcha:** el primer argumento de `Client#publish` / `#request` es **posicional** (`url`). No existe el kwarg `:path`. Splatear un hash con `path:` falla con `ArgumentError` o se ignora silencioso.
+
+**Atributos no expuestos como kwarg** (solo via block API): `timestamp` (default `Time.now.to_i`), `type` (default `full_path`), `reply_to` (RPC interno).
 
 ## Producer (bajo nivel)
 

data/spec/unit/client_session_pool_spec.rb

@@ -287,6 +287,108 @@ RSpec.describe BugBunny::Client, 'session pooling' do
     end
   end
 
+  describe 'AMQP metadata kwargs (REQUEST_ATTRS extension)' do
+    let(:fake_exchange) { double('exchange', publish: nil) }
+
+    def stub_producer_capture
+      captured = nil
+      allow_any_instance_of(BugBunny::Producer).to receive(:fire) do |_prod, req|
+        captured = req
+        { 'status' => 202, 'body' => nil }
+      end
+      allow_any_instance_of(BugBunny::Producer).to receive(:confirmed) do |_prod, req|
+        captured = req
+        { 'status' => 202, 'body' => nil }
+      end
+      [-> { captured }]
+    end
+
+    it 'persistent: true se propaga al Request via kwarg' do
+      client = described_class.new(pool: fake_pool(fake_conn))
+      get_req, = stub_producer_capture
+
+      client.publish('evt', exchange: 'x', exchange_type: 'direct', persistent: true)
+
+      expect(get_req.call.persistent).to be(true)
+    end
+
+    it 'persistent: false explícito se honra (no se filtra como falsy)' do
+      client = described_class.new(pool: fake_pool(fake_conn))
+      get_req, = stub_producer_capture
+
+      client.publish('evt', exchange: 'x', exchange_type: 'direct', persistent: false)
+
+      expect(get_req.call.persistent).to be(false)
+    end
+
+    it 'correlation_id: se propaga al Request via kwarg' do
+      client = described_class.new(pool: fake_pool(fake_conn))
+      get_req, = stub_producer_capture
+
+      client.publish('evt', exchange: 'x', exchange_type: 'direct', correlation_id: 'cid-123')
+
+      expect(get_req.call.correlation_id).to eq('cid-123')
+    end
+
+    it 'priority: se propaga al Request via kwarg' do
+      client = described_class.new(pool: fake_pool(fake_conn))
+      get_req, = stub_producer_capture
+
+      client.publish('evt', exchange: 'x', exchange_type: 'direct', priority: 9)
+
+      expect(get_req.call.priority).to eq(9)
+    end
+
+    it 'app_id, content_type, content_encoding, expiration se propagan via kwargs' do
+      client = described_class.new(pool: fake_pool(fake_conn))
+      get_req, = stub_producer_capture
+
+      client.publish('evt',
+                     exchange: 'x', exchange_type: 'direct',
+                     app_id: 'radius_manager',
+                     content_type: 'application/x-protobuf',
+                     content_encoding: 'gzip',
+                     expiration: '60000')
+
+      req = get_req.call
+      expect(req.app_id).to eq('radius_manager')
+      expect(req.content_type).to eq('application/x-protobuf')
+      expect(req.content_encoding).to eq('gzip')
+      expect(req.expiration).to eq('60000')
+    end
+
+    it 'block API sigue funcionando para atributos no expuestos como kwarg (ej: timestamp, type)' do
+      client = described_class.new(pool: fake_pool(fake_conn))
+      get_req, = stub_producer_capture
+
+      ts = Time.now.to_i - 100
+      client.publish('evt', exchange: 'x', exchange_type: 'direct') do |req|
+        req.timestamp = ts
+        req.type = 'custom.type'
+      end
+
+      req = get_req.call
+      expect(req.timestamp).to eq(ts)
+      expect(req.type).to eq('custom.type')
+    end
+
+    it 'kwargs y block API coexisten — block corre después y puede sobrescribir' do
+      client = described_class.new(pool: fake_pool(fake_conn))
+      get_req, = stub_producer_capture
+
+      client.publish('evt',
+                     exchange: 'x', exchange_type: 'direct',
+                     persistent: false, priority: 1) do |req|
+        req.persistent = true
+        req.priority = 9
+      end
+
+      req = get_req.call
+      expect(req.persistent).to be(true)
+      expect(req.priority).to eq(9)
+    end
+  end
+
   describe 'Session no se cierra entre requests' do
     it 'no invoca close en la Session al terminar el request' do
       conn   = fake_conn

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bug_bunny
 version: !ruby/object:Gem::Version
-  version: 4.16.0
+  version: 4.17.0
 platform: ruby
 authors:
 - gabix
@@ -304,7 +304,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/v4.16.0/skill
+  documentation_uri: https://github.com/gedera/bug_bunny/blob/v4.17.0/skill
 post_install_message:
 rdoc_options: []
 require_paths: