bug_bunny 4.6.1 → 4.8.0

data/docs/howto/middleware_client.md

@@ -0,0 +1,119 @@
+# Client Middleware
+
+The client middleware stack wraps outgoing requests in an onion (Faraday-style). Each middleware can inspect and modify the request before it reaches the producer, and inspect the response on the way back.
+
+## Built-in Middlewares
+
+### `BugBunny::Middleware::RaiseError`
+
+Maps HTTP-like status codes in the response to Ruby exceptions:
+
+| Status | Exception |
+|--------|-----------|
+| 400    | `BugBunny::BadRequest` |
+| 401    | `BugBunny::Unauthorized` |
+| 403    | `BugBunny::Forbidden` |
+| 404    | `BugBunny::NotFound` |
+| 409    | `BugBunny::Conflict` |
+| 422    | `BugBunny::UnprocessableEntity` |
+| 4xx    | `BugBunny::ClientError` |
+| 500    | `BugBunny::InternalServerError` |
+| 5xx    | `BugBunny::ServerError` |
+| Timeout| `BugBunny::RequestTimeout` |
+
+### `BugBunny::Middleware::JsonResponse`
+
+Parses the response body from JSON and returns a `HashWithIndifferentAccess`. Without this middleware, the response body is a raw String.
+
+---
+
+## Using Middlewares with Client
+
+```ruby
+pool   = ConnectionPool.new(size: 5, timeout: 5) { BugBunny.create_connection }
+client = BugBunny::Client.new(pool: pool) do |stack|
+  stack.use BugBunny::Middleware::RaiseError
+  stack.use BugBunny::Middleware::JsonResponse
+  stack.use MyLoggingMiddleware
+end
+```
+
+Middlewares execute in the order they are registered (FIFO). `RaiseError` and `JsonResponse` should be registered in that order so that `RaiseError` sees the parsed body.
+
+---
+
+## Writing a Custom Middleware
+
+Inherit from `BugBunny::Middleware::Base` and implement `call`:
+
+```ruby
+class RequestLoggingMiddleware < BugBunny::Middleware::Base
+  def call(request)
+    start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    response = app.call(request)
+    duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
+
+    Rails.logger.info("amqp_request path=#{request.path} method=#{request.method} duration_s=#{duration.round(4)}")
+    response
+  end
+end
+```
+
+`app.call(request)` invokes the next middleware in the stack (or the producer at the end of the chain). The return value is the response hash `{ 'status' => Integer, 'body' => ..., 'headers' => Hash }`.
+
+### Modifying the request
+
+```ruby
+class InjectTraceHeaderMiddleware < BugBunny::Middleware::Base
+  def call(request)
+    request.headers['X-Trace-Id'] = MyTracer.current_trace_id
+    app.call(request)
+  end
+end
+```
+
+### Modifying the response
+
+```ruby
+class ResponseCachingMiddleware < BugBunny::Middleware::Base
+  def call(request)
+    cached = Cache.get(request.path)
+    return cached if cached
+
+    response = app.call(request)
+    Cache.set(request.path, response, ttl: 30) if response['status'] == 200
+    response
+  end
+end
+```
+
+---
+
+## Middlewares on Resource
+
+`BugBunny::Resource` uses `RaiseError` and `JsonResponse` by default. Add custom middlewares via the class-level DSL:
+
+```ruby
+class RemoteNode < BugBunny::Resource
+  client_middleware do |stack|
+    stack.use RequestLoggingMiddleware
+    stack.use InjectTraceHeaderMiddleware
+  end
+end
+```
+
+Custom middlewares are injected after the core ones, so `RaiseError` and `JsonResponse` always run first.
+
+Middlewares defined in a parent class are inherited:
+
+```ruby
+class ApplicationResource < BugBunny::Resource
+  client_middleware do |stack|
+    stack.use InjectTraceHeaderMiddleware
+  end
+end
+
+class RemoteNode < ApplicationResource
+  # inherits InjectTraceHeaderMiddleware
+end
+```

data/docs/howto/middleware_consumer.md

@@ -0,0 +1,127 @@
+# Consumer Middleware
+
+The consumer middleware stack runs before every message reaches the router. It is the right place for cross-cutting concerns: distributed tracing, authentication, audit logging, rate limiting.
+
+## Execution Order
+
+```
+RabbitMQ message arrives
+        |
+        v
+ConsumerMiddleware::Stack
+  Middleware A (first registered)
+    Middleware B
+      Middleware C
+        process_message (router → controller → action)
+      Middleware C (post-processing)
+    Middleware B (post-processing)
+  Middleware A (post-processing)
+```
+
+Middlewares execute FIFO. If no middlewares are registered, the overhead is zero.
+
+---
+
+## Writing a Middleware
+
+Inherit from `BugBunny::ConsumerMiddleware::Base` and implement `call`:
+
+```ruby
+class TracingMiddleware < BugBunny::ConsumerMiddleware::Base
+  def call(delivery_info, properties, body)
+    trace_id = properties.headers&.dig('X-Trace-Id') || SecureRandom.uuid
+    MyTracer.with_trace(trace_id) do
+      @app.call(delivery_info, properties, body)
+    end
+  end
+end
+```
+
+`@app.call(delivery_info, properties, body)` passes control to the next middleware. Always call it (unless you intentionally want to halt processing).
+
+### Available data
+
+| Argument | Type | Contents |
+|---|---|---|
+| `delivery_info` | `Bunny::DeliveryInfo` | `routing_key`, `exchange`, `delivery_tag`, `redelivered` |
+| `properties` | `Bunny::MessageProperties` | `headers` (custom AMQP headers), `correlation_id`, `reply_to`, `content_type` |
+| `body` | `String` | Raw message payload (typically JSON) |
+
+### Post-processing
+
+Code after `@app.call` runs once the message has been fully processed (controller action completed):
+
+```ruby
+class AuditMiddleware < BugBunny::ConsumerMiddleware::Base
+  def call(delivery_info, properties, body)
+    @app.call(delivery_info, properties, body)
+  rescue => e
+    AuditLog.record_failure(routing_key: delivery_info.routing_key, error: e.class.name)
+    raise
+  ensure
+    AuditLog.record_received(routing_key: delivery_info.routing_key)
+  end
+end
+```
+
+---
+
+## Registering Middlewares
+
+```ruby
+# After BugBunny.configure
+BugBunny.consumer_middlewares.use TracingMiddleware
+BugBunny.consumer_middlewares.use AuditMiddleware
+BugBunny.consumer_middlewares.use AuthenticationMiddleware
+```
+
+Registrations are thread-safe. You can register middlewares at any point before the Consumer starts subscribing.
+
+---
+
+## Auto-registration from External Gems
+
+Integration gems can register themselves transparently when required, without the user modifying the `configure` block:
+
+```ruby
+# lib/my_tracing_gem/bug_bunny.rb
+require 'my_tracing_gem/bug_bunny/consumer_middleware'
+BugBunny.consumer_middlewares.use MyTracingGem::BugBunny::ConsumerMiddleware
+```
+
+The user only needs:
+
+```ruby
+require 'my_tracing_gem/bug_bunny'
+```
+
+---
+
+## Halting Message Processing
+
+To reject a message without routing it (e.g., authentication failure):
+
+```ruby
+class AuthMiddleware < BugBunny::ConsumerMiddleware::Base
+  def call(delivery_info, properties, body)
+    token = properties.headers&.dig('X-Service-Token')
+    unless TokenValidator.valid?(token)
+      # Do not call @app — message is effectively dropped from this consumer's perspective
+      # The channel will nack/reject it based on the consumer's error handling
+      return
+    end
+
+    @app.call(delivery_info, properties, body)
+  end
+end
+```
+
+Note: halting in a middleware skips all routing and controller logic, but the message is still acknowledged at the AMQP level (the Consumer's normal ack happens in `process_message`, which was never reached). If you need to nack/reject, interact with `delivery_info.delivery_tag` directly — but this is an advanced use case.
+
+---
+
+## Inspecting the Stack
+
+```ruby
+BugBunny.consumer_middlewares.empty?  # => false if any middleware registered
+```

data/docs/howto/rails.md

@@ -0,0 +1,214 @@
+# Rails Setup
+
+Complete integration guide for BugBunny in a Rails application using Puma and/or Sidekiq.
+
+## Gemfile
+
+```ruby
+gem 'bug_bunny'
+gem 'connection_pool'
+```
+
+## Generator
+
+```bash
+rails generate bug_bunny:install
+```
+
+Creates `config/initializers/bug_bunny.rb` with a commented template.
+
+---
+
+## Initializer
+
+```ruby
+# config/initializers/bug_bunny.rb
+
+BugBunny.configure do |config|
+  config.host     = ENV.fetch('RABBITMQ_HOST', 'localhost')
+  config.port     = ENV.fetch('RABBITMQ_PORT', '5672').to_i
+  config.username = ENV.fetch('RABBITMQ_USER', 'guest')
+  config.password = ENV.fetch('RABBITMQ_PASS', 'guest')
+  config.vhost    = ENV.fetch('RABBITMQ_VHOST', '/')
+
+  config.rpc_timeout               = 30
+  config.max_reconnect_attempts    = 10
+  config.max_reconnect_interval    = 60
+  config.network_recovery_interval = 5
+
+  config.exchange_options = { durable: true }
+  config.queue_options    = { durable: true }
+
+  config.logger = Rails.logger
+
+  # Kubernetes / Docker Swarm liveness probe
+  config.health_check_file = Rails.root.join('tmp', 'bug_bunny_health').to_s
+end
+
+# Shared connection pool — size should match Puma/Sidekiq thread count
+BUG_BUNNY_POOL = ConnectionPool.new(
+  size:    ENV.fetch('RAILS_MAX_THREADS', 5).to_i,
+  timeout: 5
+) do
+  BugBunny.create_connection
+end
+
+# Make the pool available to all Resource classes
+BugBunny::Resource.connection_pool = BUG_BUNNY_POOL
+```
+
+---
+
+## Routes
+
+```ruby
+# config/initializers/bug_bunny_routes.rb
+BugBunny.routes.draw do
+  resources :users
+  resources :orders do
+    member { post :cancel }
+  end
+end
+```
+
+Keep routes in a dedicated initializer so they load independently from `config/routes.rb`.
+
+---
+
+## Directory Layout
+
+The Rails generator configures Zeitwerk to autoload `app/rabbit`:
+
+```
+app/
+  rabbit/
+    controllers/          # BugBunny controllers (loaded under BugBunny::Controllers)
+      application_controller.rb
+      users_controller.rb
+    workers/              # Consumer processes (optional)
+      inventory_worker.rb
+```
+
+Or use the configurable controller namespace:
+
+```ruby
+config.controller_namespace = 'Rabbit::Controllers'
+# → app/rabbit/controllers/ maps to Rabbit::Controllers
+```
+
+---
+
+## Consumer Workers
+
+The Consumer is a blocking subscribe loop. Run it in a dedicated process (not inside Puma).
+
+### Rake task
+
+```ruby
+# lib/tasks/rabbit.rake
+namespace :rabbit do
+  desc 'Start the RabbitMQ consumer'
+  task inventory: :environment do
+    consumer = BugBunny::Consumer.new
+    trap('TERM') { consumer.shutdown; exit }
+    trap('INT')  { consumer.shutdown; exit }
+
+    consumer.subscribe(
+      queue_name:    'inventory_queue',
+      exchange_name: 'inventory_exchange',
+      routing_key:   'inventory',
+      block:         true
+    )
+  end
+end
+```
+
+```bash
+bundle exec rake rabbit:inventory
+```
+
+### Dockerfile entrypoint (separate service)
+
+```dockerfile
+# Dockerfile.worker
+CMD ["bundle", "exec", "rake", "rabbit:inventory"]
+```
+
+### Multiple consumers
+
+Run one process per queue. Each process has its own connection pool.
+
+---
+
+## Puma Fork Safety
+
+When Puma forks workers, open AMQP connections in the parent process become invalid in children. BugBunny's Railtie handles this automatically for Puma via `on_worker_boot`:
+
+```ruby
+# Railtie registers this automatically:
+Puma::Server.on_worker_boot do
+  BugBunny.reconnect! if defined?(BUG_BUNNY_POOL)
+end
+```
+
+If you use a custom pool variable name, add the hook manually:
+
+```ruby
+# config/puma.rb
+on_worker_boot do
+  MY_CUSTOM_POOL.reload_connections { BugBunny.create_connection }
+end
+```
+
+---
+
+## Sidekiq Integration
+
+Sidekiq uses threads, not forks, so no special handling is needed. The shared `BUG_BUNNY_POOL` is thread-safe. Sidekiq jobs can call `BugBunny::Resource` methods directly.
+
+Set the pool size to match Sidekiq's concurrency:
+
+```ruby
+BUG_BUNNY_POOL = ConnectionPool.new(
+  size: ENV.fetch('SIDEKIQ_CONCURRENCY', 10).to_i,
+  timeout: 5
+) { BugBunny.create_connection }
+```
+
+---
+
+## Health Checks (Kubernetes / Docker Swarm)
+
+The Consumer's internal heartbeat timer touches `config.health_check_file` every 30 seconds after verifying the RabbitMQ connection and queue are alive.
+
+```yaml
+# docker-compose.yml
+healthcheck:
+  test: ["CMD", "test", "-f", "/app/tmp/bug_bunny_health"]
+  interval: 60s
+  timeout: 5s
+  retries: 3
+  start_period: 30s  # allow time for Rails boot + first heartbeat
+```
+
+```yaml
+# Kubernetes
+livenessProbe:
+  exec:
+    command: ["test", "-f", "/app/tmp/bug_bunny_health"]
+  initialDelaySeconds: 30
+  periodSeconds: 60
+```
+
+---
+
+## Graceful Shutdown
+
+The `Consumer#shutdown` method stops the heartbeat timer and closes the AMQP channel cleanly. It is also called automatically when `subscribe` exits for any reason.
+
+```ruby
+consumer = BugBunny::Consumer.new
+trap('TERM') { consumer.shutdown; exit 0 }
+trap('INT')  { consumer.shutdown; exit 0 }
+consumer.subscribe(...)
+```

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'
+```