bug_bunny 4.6.1 → 4.7.0

data/docs/howto/resource.md

@@ -0,0 +1,200 @@
+# Resource ORM
+
+`BugBunny::Resource` provides an ActiveRecord-like interface for remote services. Each Resource class represents a resource type in another microservice, reachable via RabbitMQ.
+
+## Defining a Resource
+
+```ruby
+class RemoteNode < BugBunny::Resource
+  # AMQP infrastructure
+  self.exchange      = 'inventory_exchange'
+  self.exchange_type = 'direct'           # default
+  self.resource_name = 'nodes'            # used as the path prefix and routing key
+
+  # Typed attributes (ActiveModel::Attributes)
+  attribute :name,      :string
+  attribute :status,    :string
+  attribute :cpu_cores, :integer
+  attribute :active,    :boolean
+
+  # Validations (ActiveModel::Validations)
+  validates :name,   presence: true
+  validates :status, inclusion: { in: %w[pending active draining decommissioned] }
+end
+```
+
+## Connection Pool
+
+All Resource classes in a service typically share one pool:
+
+```ruby
+# config/initializers/bug_bunny.rb
+BUG_BUNNY_POOL = ConnectionPool.new(size: 5, timeout: 5) do
+  BugBunny.create_connection
+end
+
+BugBunny::Resource.connection_pool = BUG_BUNNY_POOL
+```
+
+Individual classes can override:
+
+```ruby
+RemoteNode.connection_pool = OTHER_POOL
+```
+
+---
+
+## CRUD
+
+```ruby
+# Find by ID — returns nil on 404
+node = RemoteNode.find('node-123')
+
+# List all
+nodes = RemoteNode.all
+
+# Filter — query params forwarded to the consumer
+nodes = RemoteNode.where(status: 'active')
+nodes = RemoteNode.where(q: { cpu_cores: 4 }, page: 2)
+
+# Create
+node = RemoteNode.create(name: 'web-01', status: 'pending')
+node.persisted?  # => true if save succeeded
+
+# Update
+node = RemoteNode.find('node-123')
+node.status = 'active'
+node.save        # PUT nodes/node-123
+
+# Update (shorthand)
+node.update(status: 'active', name: 'web-01')
+
+# Destroy
+node.destroy     # DELETE nodes/node-123
+```
+
+---
+
+## Typed vs Dynamic Attributes
+
+### Typed attributes
+
+Declared with `attribute :name, :type`. Benefit from ActiveModel coercions, dirty tracking, and validations:
+
+```ruby
+attribute :cpu_cores, :integer
+attribute :enabled,   :boolean
+attribute :score,     :decimal
+```
+
+### Dynamic attributes
+
+Any key received from the remote service that is not declared as a typed attribute is stored dynamically and accessible via `method_missing`:
+
+```ruby
+node = RemoteNode.find('node-123')
+node.docker_id      # => "abc123xyz" (not declared, but present in the response)
+node.docker_id = 'new-id'
+node.changed?       # => true
+node.changed        # => ['docker_id']
+```
+
+Dynamic attributes participate in `changed?`, `changed`, and `changes_to_send` — so they are serialized correctly on `save`.
+
+---
+
+## Change Tracking
+
+BugBunny::Resource merges ActiveModel::Dirty (for typed attributes) with its own tracking for dynamic attributes.
+
+```ruby
+node = RemoteNode.find('node-123')  # changes cleared after find
+node.changed?                       # => false
+
+node.status = 'draining'
+node.changed?                       # => true
+node.changed                        # => ['status']
+
+node.save                           # sends only changed attrs
+node.changed?                       # => false (cleared after save)
+```
+
+`save` on a new record (not persisted) sends all attributes.
+
+---
+
+## Validations
+
+```ruby
+node = RemoteNode.new(name: '', status: 'invalid')
+node.valid?          # => false
+node.errors.full_messages
+# => ["Name can't be blank", "Status is not included in the list"]
+
+node.save            # => false (does not send the request)
+```
+
+Remote validation errors (422 responses) are loaded back into the object:
+
+```ruby
+node = RemoteNode.create(name: 'duplicate-name')
+node.persisted?                    # => false
+node.errors[:name]                 # => ["has already been taken"]
+```
+
+---
+
+## Callbacks
+
+```ruby
+class RemoteNode < BugBunny::Resource
+  before_save  :normalize_name
+  after_create :notify_provisioner
+  around_save  :with_timing
+
+  private
+
+  def normalize_name
+    self.name = name.to_s.downcase.strip
+  end
+end
+```
+
+Available callbacks: `before_save`, `after_save`, `before_create`, `after_create`, `before_update`, `after_update`, `before_destroy`, `after_destroy`.
+
+---
+
+## Dynamic Exchange Configuration with `.with`
+
+Override AMQP settings for a single operation without changing the class defaults:
+
+```ruby
+# Different exchange for a single call
+RemoteNode.with(exchange: 'us-east-inventory').where(status: 'active')
+
+# Different routing key
+RemoteNode.with(routing_key: 'nodes.priority').find('node-123')
+
+# Chain is single-use — call .with again for the next operation
+RemoteNode.with(exchange: 'staging').create(name: 'test-node')
+```
+
+`.with` sets thread-local values that are cleaned up after the single operation completes, even if an exception is raised.
+
+---
+
+## Payload Wrapping
+
+By default, `save` wraps the payload under a root key derived from the model name:
+
+```ruby
+# RemoteNode → root key: 'node'
+node.save
+# Sends: { "node" => { "name" => "web-01", "status" => "active" } }
+```
+
+The consumer can then use `params.require(:node)` in the controller. Override the root key:
+
+```ruby
+self.param_key = 'server'
+```

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.