bug_bunny 4.6.1 → 4.8.0

data/docs/howto/routing.md

@@ -0,0 +1,133 @@
+# Routing
+
+Routes declare how incoming AMQP messages map to controllers and actions. They are evaluated on every message received by the Consumer.
+
+## Drawing Routes
+
+Define routes in an initializer (or any file loaded at boot):
+
+```ruby
+BugBunny.routes.draw do
+  # routes here
+end
+```
+
+Call `draw` only once. Multiple calls replace the previous route set.
+
+---
+
+## HTTP Verbs
+
+```ruby
+BugBunny.routes.draw do
+  get    'status',        to: 'health#show'
+  post   'events',        to: 'events#create'
+  put    'users/:id',     to: 'users#update'
+  delete 'users/:id',     to: 'users#destroy'
+end
+```
+
+The verb is set by the producer via the `x-http-method` AMQP header. `BugBunny::Resource` and `BugBunny::Client` set it automatically.
+
+Dynamic segments (`:id`) are extracted from the path and available in `params` inside the controller.
+
+---
+
+## Resources Macro
+
+`resources` generates the standard seven CRUD routes in one line:
+
+```ruby
+resources :users
+```
+
+Generates:
+
+| Verb   | Path          | Action    |
+|--------|---------------|-----------|
+| GET    | users         | index     |
+| POST   | users         | create    |
+| GET    | users/:id     | show      |
+| PUT    | users/:id     | update    |
+| DELETE | users/:id     | destroy   |
+
+### Filtering actions
+
+```ruby
+resources :orders, only: [:index, :show, :create]
+resources :logs,   except: [:update, :destroy]
+```
+
+---
+
+## Member and Collection Routes
+
+```ruby
+resources :nodes do
+  member do
+    put  :drain      # PUT  nodes/:id/drain   → NodesController#drain
+    post :reboot     # POST nodes/:id/reboot  → NodesController#reboot
+  end
+
+  collection do
+    post :rebalance  # POST nodes/rebalance   → NodesController#rebalance
+    get  :summary    # GET  nodes/summary     → NodesController#summary
+  end
+end
+```
+
+Member routes receive `params[:id]` automatically. Collection routes do not.
+
+---
+
+## Namespace Blocks
+
+Group routes under a controller namespace. Namespaces stack: nested `namespace` blocks accumulate with `::`.
+
+```ruby
+BugBunny.routes.draw do
+  namespace :api do
+    namespace :v1 do
+      resources :metrics     # → Api::V1::MetricsController
+      resources :alerts      # → Api::V1::AlertsController
+    end
+
+    resources :health        # → Api::HealthController
+  end
+
+  resources :nodes           # → BugBunny::Controllers::NodesController (global namespace)
+end
+```
+
+The namespace in the route takes precedence over `config.controller_namespace`. Routes without a namespace block use the global controller namespace.
+
+---
+
+## Nested Resources
+
+```ruby
+resources :clusters do
+  resources :nodes do        # → nodes/:id nested under clusters/:cluster_id
+    member { put :drain }
+  end
+end
+```
+
+Nested resource routes inject all parent IDs into params. Example: `PUT clusters/c1/nodes/n2/drain` → `params[:cluster_id] = 'c1'`, `params[:id] = 'n2'`.
+
+---
+
+## Inspecting Routes
+
+```ruby
+BugBunny.routes.recognize('GET', 'nodes/123')
+# => { controller: 'nodes', action: 'show', params: { 'id' => '123' }, namespace: nil }
+
+BugBunny.routes.recognize('POST', 'api/v1/metrics')
+# => { controller: 'metrics', action: 'create', params: {}, namespace: 'Api::V1' }
+
+BugBunny.routes.recognize('GET', 'unknown/path')
+# => nil
+```
+
+Useful in tests to verify route definitions without sending real messages.

data/docs/howto/testing.md

@@ -0,0 +1,259 @@
+# 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

@@ -0,0 +1,119 @@
+# 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/lib/bug_bunny/client.rb

@@ -31,6 +31,7 @@ module BugBunny
     # @raise [ArgumentError] Si no se proporciona un `pool`.
     def initialize(pool:)
       raise ArgumentError, "BugBunny::Client requiere un 'pool:'" if pool.nil?
+
       @pool = pool
       @stack = BugBunny::Middleware::Stack.new
       @delivery_mode = :rpc
@@ -96,7 +97,7 @@ module BugBunny
       req = BugBunny::Request.new(url)
 
       # 2. Syntactic Sugar: Mapeo de argumentos a atributos del Request
-      req.delivery_mode    = delivery_mode           # Default del cliente
+      req.delivery_mode    = delivery_mode # Default del cliente
       req.delivery_mode    = args[:delivery_mode]    if args[:delivery_mode]
       req.method           = args[:method]           if args[:method]
       req.body             = args[:body]             if args[:body]
@@ -109,33 +110,56 @@ module BugBunny
       req.exchange_options = args[:exchange_options] if args[:exchange_options]
       req.queue_options    = args[:queue_options]    if args[:queue_options]
 
-      req.params                                     = args[:params]   if args[:params]
-      req.headers.merge!(args[:headers])             if args[:headers]
+      req.params = args[:params] if args[:params]
+      req.headers.merge!(args[:headers]) if args[:headers]
 
       # 3. Configuración del usuario (bloque específico por request)
       yield req if block_given?
 
       # 4. Ejecución dentro del Pool
+      # Session y Producer se reutilizan por slot de conexión (ver #session_for / #producer_for).
       @pool.with do |conn|
-        session = BugBunny::Session.new(conn)
-        producer = BugBunny::Producer.new(session)
-
-        begin
-          # Mapeo de delivery_mode al método del productor (:rpc o :fire)
-          # :publish se mapea a :fire por consistencia interna.
-          method_name = req.delivery_mode == :publish ? :fire : :rpc
-
-          # Onion Architecture: La acción final es llamar al Producer real.
-          final_action = ->(env) { producer.send(method_name, env) }
-
-          # Construimos y ejecutamos la cadena de middlewares
-          app = @stack.build(final_action)
-          app.call(req)
-        ensure
-          # Aseguramos el cierre del canal pero mantenemos la conexión del pool
-          session.close
-        end
+        session  = session_for(conn)
+        producer = producer_for(conn, session)
+
+        # Mapeo de delivery_mode al método del productor (:rpc o :fire)
+        method_name  = req.delivery_mode == :publish ? :fire : :rpc
+
+        # Onion Architecture: La acción final es llamar al Producer real.
+        final_action = ->(env) { producer.send(method_name, env) }
+
+        # Construimos y ejecutamos la cadena de middlewares
+        app = @stack.build(final_action)
+        app.call(req)
       end
     end
+
+    # Recupera o crea la Session asociada al slot de conexión dado.
+    #
+    # La Session (y su canal AMQP) se almacena como ivar en el objeto `conn`.
+    # Thread-safe sin mutex adicional: ConnectionPool garantiza que cada `conn`
+    # es usado por un único thread a la vez.
+    #
+    # @param conn [Bunny::Session] Conexión activa del pool.
+    # @return [BugBunny::Session]
+    def session_for(conn)
+      conn.instance_variable_get(:@_bug_bunny_session) ||
+        conn.instance_variable_set(:@_bug_bunny_session, BugBunny::Session.new(conn))
+    end
+
+    # Recupera o crea el Producer asociado al slot de conexión dado.
+    #
+    # El Producer debe cachearse junto con la Session porque registra un
+    # `basic_consume` sobre el canal para escuchar replies RPC. Si se creara
+    # un Producer nuevo por request (con el canal reutilizado), se intentaría
+    # registrar un segundo consumidor sobre el mismo canal, causando un error AMQP.
+    #
+    # @param conn [Bunny::Session] Conexión activa del pool.
+    # @param session [BugBunny::Session] Session ya resuelta para `conn`.
+    # @return [BugBunny::Producer]
+    def producer_for(conn, session)
+      conn.instance_variable_get(:@_bug_bunny_producer) ||
+        conn.instance_variable_set(:@_bug_bunny_producer, BugBunny::Producer.new(session))
+    end
   end
 end

data/lib/bug_bunny/configuration.rb

@@ -14,6 +14,28 @@ module BugBunny
   #     config.health_check_file = '/tmp/bug_bunny_health'
   #   end
   class Configuration
+    # Reglas de validación por atributo.
+    # Solo cubre los atributos de conexión y timeout — los demás (logger, procs, hashes)
+    # son tipos arbitrarios que no tienen sentido validar de forma genérica.
+    #
+    # Claves soportadas:
+    # - `:type`     — clase que debe responder `is_a?`
+    # - `:required` — si `true`, nil o string vacío lanzan ConfigurationError
+    # - `:range`    — rango válido de valores (solo para Integer)
+    VALIDATIONS = {
+      host: { type: String, required: true },
+      port: { type: Integer, required: true, range: 1..65_535 },
+      username: { type: String, required: true },
+      password: { type: String, required: true },
+      vhost: { type: String, required: true },
+      heartbeat: { type: Integer, range: 0..3_600 },
+      connection_timeout: { type: Integer, range: 1..300 },
+      read_timeout: { type: Integer, range: 1..300 },
+      write_timeout: { type: Integer, range: 1..300 },
+      rpc_timeout: { type: Integer, range: 1..3_600 },
+      channel_prefetch: { type: Integer, range: 1..10_000 }
+    }.freeze
+
     # @return [String] Host o IP del servidor RabbitMQ (ej: 'localhost').
     attr_accessor :host
 
@@ -163,5 +185,46 @@ module BugBunny
     def url
       "amqp://#{username}:#{password}@#{host}:#{port}/#{vhost}"
     end
+
+    # Valida todos los atributos definidos en {VALIDATIONS}.
+    # Se invoca automáticamente al final de {BugBunny.configure}.
+    #
+    # @raise [BugBunny::ConfigurationError] Si algún atributo es inválido.
+    # @return [void]
+    def validate!
+      VALIDATIONS.each do |attr, rules|
+        value = send(attr)
+        validate_required!(attr, value, rules)
+        next if value.nil?
+
+        validate_type!(attr, value, rules)
+        validate_range!(attr, value, rules)
+      end
+    end
+
+    private
+
+    def validate_required!(attr, value, rules)
+      return unless rules[:required]
+      return unless value.nil? || (value.is_a?(String) && value.empty?)
+
+      raise BugBunny::ConfigurationError, "#{attr} is required"
+    end
+
+    def validate_type!(attr, value, rules)
+      return unless rules[:type]
+      return if value.is_a?(rules[:type])
+
+      raise BugBunny::ConfigurationError,
+            "#{attr} must be a #{rules[:type]}, got #{value.class}"
+    end
+
+    def validate_range!(attr, value, rules)
+      return unless rules[:range]
+      return if rules[:range].cover?(value)
+
+      raise BugBunny::ConfigurationError,
+            "#{attr} must be in #{rules[:range]}, got #{value.inspect}"
+    end
   end
 end