bug_bunny 4.8.0 → 4.8.1

data/docs/howto/middleware_consumer.md

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

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

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

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