bug_bunny 4.8.0 → 4.9.0

data/docs/howto/routing.md

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

@@ -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.