bug_bunny 4.7.0 → 4.8.1

data/docs/howto/testing.md

@@ -1,259 +0,0 @@
-# Testing
-
-BugBunny applications can be tested at two levels: **unit tests** (with Bunny doubles) and **integration tests** (with a full mocked AMQP stack). No real RabbitMQ server is required.
-
-## Setup
-
-```ruby
-# spec/spec_helper.rb
-require 'bug_bunny'
-require 'rspec'
-
-Dir[File.join(__dir__, 'support', '**', '*.rb')].each { |f| require f }
-
-RSpec.configure do |config|
-  config.before(:each) do
-    # Reset global state between tests
-    BugBunny.instance_variable_set(:@consumer_middlewares, nil)
-    BugBunny.instance_variable_set(:@routes, nil)
-  end
-end
-```
-
----
-
-## Bunny Doubles
-
-Create lightweight doubles for Bunny objects so tests never touch the network:
-
-```ruby
-# spec/support/bunny_mocks.rb
-
-def build_bunny_channel(opts = {})
-  channel = instance_double(Bunny::Channel)
-  allow(channel).to receive(:open?).and_return(true)
-  allow(channel).to receive(:prefetch)
-  allow(channel).to receive(:confirm_select)
-  allow(channel).to receive(:ack)
-  allow(channel).to receive(:reject)
-  allow(channel).to receive(:close)
-  allow(channel).to receive(:default_exchange).and_return(build_bunny_exchange)
-  allow(channel).to receive(:topic).and_return(build_bunny_exchange)
-  allow(channel).to receive(:direct).and_return(build_bunny_exchange)
-  channel
-end
-
-def build_bunny_connection(opts = {})
-  conn = instance_double(Bunny::Session)
-  allow(conn).to receive(:open?).and_return(true)
-  allow(conn).to receive(:start)
-  allow(conn).to receive(:create_channel).and_return(build_bunny_channel)
-  conn
-end
-
-def build_bunny_exchange
-  exchange = instance_double(Bunny::Exchange)
-  allow(exchange).to receive(:publish)
-  exchange
-end
-```
-
----
-
-## Unit Testing Controllers
-
-Test controller actions directly via `Controller.call`, bypassing AMQP entirely:
-
-```ruby
-RSpec.describe NodesController do
-  let(:node) { Node.new(id: '42', name: 'web-01', status: 'active') }
-
-  describe '#show' do
-    it 'returns the node as JSON' do
-      allow(Node).to receive(:find).with('42').and_return(node)
-
-      response = NodesController.call(
-        headers: { type: 'nodes/42', 'x-http-method' => 'GET' },
-        body: ''
-      )
-
-      expect(response[:status]).to eq(200)
-      expect(response[:body][:name]).to eq('web-01')
-    end
-  end
-
-  describe '#show with missing node' do
-    it 'returns 404' do
-      allow(Node).to receive(:find).with('99').and_return(nil)
-
-      response = NodesController.call(
-        headers: { type: 'nodes/99', 'x-http-method' => 'GET' },
-        body: ''
-      )
-
-      expect(response[:status]).to eq(404)
-    end
-  end
-end
-```
-
----
-
-## Unit Testing before_action / after_action
-
-```ruby
-RSpec.describe NodesController do
-  describe 'before_action :authenticate!' do
-    it 'returns 401 when token is missing' do
-      response = NodesController.call(
-        headers: { type: 'nodes', 'x-http-method' => 'GET' },
-        body: ''
-        # no X-Service-Token header
-      )
-
-      expect(response[:status]).to eq(401)
-    end
-  end
-
-  describe 'after_action :emit_audit_event' do
-    it 'emits an audit event after create' do
-      expect(AuditLog).to receive(:record).with(hash_including(action: 'create'))
-
-      NodesController.call(
-        headers: { type: 'nodes', 'x-http-method' => 'POST', 'X-Service-Token' => 'valid' },
-        body: '{"node":{"name":"web-01","status":"pending"}}'
-      )
-    end
-  end
-end
-```
-
----
-
-## Unit Testing Consumer Middleware
-
-```ruby
-RSpec.describe TracingMiddleware do
-  subject(:middleware) { described_class.new(terminal) }
-
-  let(:terminal) { ->(di, props, body) { :processed } }
-  let(:delivery_info) { instance_double(Bunny::DeliveryInfo, routing_key: 'nodes') }
-  let(:properties) do
-    instance_double(Bunny::MessageProperties,
-      headers: { 'X-Trace-Id' => 'trace-123' },
-      correlation_id: 'corr-456'
-    )
-  end
-
-  it 'extracts the trace header and sets context' do
-    expect(MyTracer).to receive(:with_trace).with('trace-123').and_yield
-
-    middleware.call(delivery_info, properties, '{}')
-  end
-
-  it 'generates a new trace id when header is absent' do
-    allow(properties).to receive(:headers).and_return({})
-    expect(MyTracer).to receive(:with_trace).with(be_a(String)).and_yield
-
-    middleware.call(delivery_info, properties, '{}')
-  end
-end
-```
-
----
-
-## Integration Testing with a Mock Consumer
-
-For tests that exercise the full routing + controller stack, use an in-process integration helper:
-
-```ruby
-# spec/support/integration_helper.rb
-
-module IntegrationHelper
-  def process_message(method:, path:, body: '', headers: {})
-    delivery_info = instance_double(Bunny::DeliveryInfo,
-      delivery_tag: 1,
-      routing_key: 'test'
-    )
-
-    properties = instance_double(Bunny::MessageProperties,
-      type: path,
-      reply_to: nil,
-      correlation_id: SecureRandom.uuid,
-      headers: { 'x-http-method' => method.to_s.upcase }.merge(headers)
-    )
-
-    consumer = BugBunny::Consumer.new
-    # Allow channel operations on the mock session
-    allow(consumer.session.channel).to receive(:ack)
-    allow(consumer.session.channel).to receive(:reject)
-    allow(consumer.session.channel).to receive(:default_exchange).and_return(build_bunny_exchange)
-
-    consumer.send(:process_message, delivery_info, properties, body.to_json)
-  end
-end
-
-RSpec.configure do |config|
-  config.include IntegrationHelper, type: :integration
-end
-```
-
-```ruby
-# spec/integration/nodes_spec.rb, type: :integration
-RSpec.describe 'Nodes API', type: :integration do
-  before do
-    BugBunny.routes.draw { resources :nodes }
-  end
-
-  it 'routes GET nodes/:id to NodesController#show' do
-    allow(Node).to receive(:find).with('42').and_return(Node.new(id: 42, name: 'web-01'))
-
-    process_message(method: :get, path: 'nodes/42')
-
-    expect(Node).to have_received(:find).with('42')
-  end
-
-  it 'returns 404 for unregistered routes' do
-    response = process_message(method: :get, path: 'unknown/path')
-    # response is captured via the consumer's handle_fatal_error path
-  end
-end
-```
-
----
-
-## Unit Testing Configuration Validation
-
-```ruby
-RSpec.describe BugBunny::Configuration do
-  describe '#validate!' do
-    it 'raises ConfigurationError when host is blank' do
-      config = described_class.new
-      config.host = ''
-
-      expect { config.validate! }.to raise_error(BugBunny::ConfigurationError, /host is required/)
-    end
-
-    it 'raises ConfigurationError when port is out of range' do
-      config = described_class.new
-      config.host = 'localhost'
-      config.port = 99_999
-
-      expect { config.validate! }.to raise_error(BugBunny::ConfigurationError, /port must be in/)
-    end
-  end
-end
-```
-
----
-
-## Running Tests
-
-```bash
-source /opt/homebrew/opt/chruby/share/chruby/chruby.sh && chruby ruby-3.3.8
-
-bundle exec rspec                          # all tests
-bundle exec rspec spec/unit/               # unit tests only
-bundle exec rspec spec/integration/        # integration tests only
-bundle exec rspec spec/unit/consumer_spec.rb  # single file
-```

data/docs/howto/tracing.md

@@ -1,119 +0,0 @@
-# Distributed Tracing
-
-BugBunny propagates trace context through the full RPC cycle, from the producer to the consumer and back. The mechanism is tracer-agnostic: BugBunny provides hooks and you supply the tracer-specific logic.
-
-## What BugBunny Propagates by Default
-
-The `correlation_id` AMQP property travels automatically from producer to consumer on every request. The Consumer wraps the entire execution in a `logger.tagged(correlation_id)` block when the logger supports tagged logging (Rails' `ActiveSupport::TaggedLogging`).
-
-This alone connects producer and consumer log lines without any configuration.
-
----
-
-## Full Bidirectional Propagation
-
-For distributed tracing systems (OpenTelemetry, AWS X-Ray, Datadog APM, etc.) you need to:
-
-1. **Inject** the current trace header into outgoing requests (producer side).
-2. **Extract** the trace header from incoming messages (consumer side) — done via Consumer Middleware.
-3. **Re-inject** the updated trace header into the RPC reply (consumer side).
-4. **Hydrate** the trace context from the reply headers back in the calling thread (producer side).
-
-Steps 3 and 4 handle the case where the consumer creates a child span — the parent needs to know about it.
-
----
-
-## Configuration Hooks
-
-### `rpc_reply_headers`
-
-A `Proc` called in the consumer thread just before sending the RPC reply. Its return value is merged into the reply AMQP headers.
-
-```ruby
-BugBunny.configure do |config|
-  config.rpc_reply_headers = -> {
-    { 'X-Trace-Header' => MyTracer.outgoing_header }
-  }
-end
-```
-
-Zero overhead when not set.
-
-### `on_rpc_reply`
-
-A `Proc` called in the producer thread after the RPC reply arrives, with the reply headers as argument. Use it to hydrate the trace context in the calling thread.
-
-```ruby
-BugBunny.configure do |config|
-  config.on_rpc_reply = ->(headers) {
-    MyTracer.hydrate(headers['X-Trace-Header'])
-  }
-end
-```
-
----
-
-## Full Example (tracer-agnostic)
-
-```ruby
-# config/initializers/bug_bunny.rb
-
-BugBunny.configure do |config|
-  # ... connection config ...
-
-  # Step 3: inject updated trace header into RPC reply
-  config.rpc_reply_headers = -> {
-    { 'X-Trace-Header' => MyTracer.generate_outgoing_header }
-  }
-
-  # Step 4: hydrate trace context in the producer thread after reply
-  config.on_rpc_reply = ->(headers) {
-    MyTracer.hydrate_from_header(headers['X-Trace-Header'])
-  }
-end
-
-# Step 1: inject trace header into outgoing requests (client middleware)
-class TraceInjectionMiddleware < BugBunny::Middleware::Base
-  def call(request)
-    request.headers['X-Trace-Header'] = MyTracer.generate_outgoing_header
-    app.call(request)
-  end
-end
-
-# Step 2: extract trace header from incoming messages (consumer middleware)
-class TraceExtractionMiddleware < BugBunny::ConsumerMiddleware::Base
-  def call(delivery_info, properties, body)
-    incoming_header = properties.headers&.dig('X-Trace-Header')
-    MyTracer.with_trace_from_header(incoming_header) do
-      @app.call(delivery_info, properties, body)
-    end
-  end
-end
-
-# Register both
-BugBunny::Resource.client_middleware { |s| s.use TraceInjectionMiddleware }
-BugBunny.consumer_middlewares.use TraceExtractionMiddleware
-```
-
----
-
-## Fire-and-Forget Tracing
-
-For `:publish` (fire-and-forget) calls, there is no reply, so `on_rpc_reply` and `rpc_reply_headers` do not apply. Use only the client middleware to inject the outgoing trace header:
-
-```ruby
-class TraceInjectionMiddleware < BugBunny::Middleware::Base
-  def call(request)
-    request.headers['X-Trace-Header'] = MyTracer.generate_outgoing_header
-    app.call(request)
-  end
-end
-```
-
-The consumer middleware extracts it on the other side regardless of whether the call was RPC or fire-and-forget.
-
----
-
-## correlation_id
-
-BugBunny sets `correlation_id` automatically on every RPC request (used internally to match replies). It is also forwarded as a log tag. If your tracer uses a separate header (e.g., `traceparent`), use the `X-Trace-Header` pattern above. If you want to use `correlation_id` as the trace ID, read it from `properties.correlation_id` in your consumer middleware.

data/mejoras.md

@@ -1,33 +0,0 @@
-1. Robustez en el Manejo de Conexiones
-Actualmente, el Producer y el Consumer dependen de que la sesión esté abierta al momento de instanciarse.
-
-Mejora sugerida: Implementar una lógica de "Reconexión Transparente". Si el socket de RabbitMQ se cierra por un problema de red, la gema debería intentar restablecer la conexión automáticamente antes de lanzar una excepción.
-
-Lazy Loading de Canales: Actualmente se crea el canal al inicializar la sesión. Podrías retrasar la creación del canal hasta el primer publish o subscribe para evitar consumir recursos si la gema está cargada pero no se usa inmediatamente.
-
-2. Estandarización de BugBunny::Resource
-Durante los tests de Resource, notamos que los atributos son puramente dinámicos vía method_missing.
-
-Mejora sugerida: Integrar formalmente ActiveModel::Attributes (que ya incluyes parcialmente) para permitir la definición explícita de tipos.
-
-Ejemplo: attribute :price, :decimal.
-
-Esto permitiría que la gema realice conversiones de tipo (coerción) automáticamente antes de enviar el JSON, evitando errores de tipo en el microservicio de destino.
-
-3. Observabilidad y Debugging
-Los tests de integración mostraron que identificar fallos en el flujo RPC puede ser difícil sin los logs adecuados.
-
-Mejora sugerida: Tracing ID (Correlation ID) automático. * Aunque ya usas correlation_id para el emparejamiento de respuestas, podrías integrar un middleware que inyecte este ID en todos los logs de Rails.
-
-Esto permitiría seguir el rastro de una petición desde que sale del Client hasta que el Consumer la procesa en otro servidor.
-
-4. Soporte para Namespaces en Controladores
-El Consumer busca controladores en el namespace rígido Rabbit::Controllers.
-
-Mejora sugerida: Permitir configurar el namespace base. Si el usuario quiere organizar sus controladores en Messaging::Handlers en lugar de Rabbit::Controllers, la gema debería permitirlo mediante una opción en el inicializador.
-
-5. No veo que en el controller que hicimos sea facil manipular el header
-
-
-Vamos a ir resolviendo este en etapas. del punto 1 al 5. Solo pasamos al proximo punto si quedo el actual resuelto.
-Importante: Todas las modificaciones que sean completadas, robustas y claramente documentadas con YARD.