bug_bunny 4.8.0 → 4.8.1

data/docs/ai/api.md

@@ -1,251 +0,0 @@
-## Public API
-
-### BugBunny.configure
-
-```ruby
-BugBunny.configure do |config|
-  config.host     = 'localhost'       # String, required
-  config.port     = 5672              # Integer 1..65535, required
-  config.username = 'guest'           # String, required
-  config.password = 'guest'           # String, required
-  config.vhost    = '/'               # String, required
-
-  config.rpc_timeout            = 10   # Integer 1..3600, seconds
-  config.channel_prefetch       = 1    # Integer 1..10000
-  config.max_reconnect_attempts = nil  # nil = infinite
-  config.max_reconnect_interval = 60   # seconds, backoff ceiling
-  config.network_recovery_interval = 5 # seconds, backoff base
-
-  config.exchange_options = { durable: true }
-  config.queue_options    = { durable: true }
-
-  config.logger             = Rails.logger
-  config.health_check_file  = Rails.root.join('tmp/bug_bunny_health').to_s
-
-  config.controller_namespace = 'Rabbit::Controllers'
-
-  # Trace propagation hooks
-  config.rpc_reply_headers = -> { { 'X-Trace-Id' => Tracer.current_header } }
-  config.on_rpc_reply      = ->(headers) { Tracer.hydrate(headers['X-Trace-Id']) }
-end
-```
-
-`validate!` is called automatically at the end of `configure`. Raises `BugBunny::ConfigurationError` on invalid values.
-
----
-
-### BugBunny.routes
-
-```ruby
-BugBunny.routes.draw do
-  resources :users                          # index, show, create, update, destroy
-  resources :orders do
-    member     { post :cancel }             # POST orders/:id/cancel
-    collection { get  :pending }            # GET  orders/pending
-  end
-  namespace :admin do
-    resources :reports                      # Admin::Controllers::ReportsController
-  end                                       # path prefix: admin/reports
-end
-```
-
-**recognize:**
-```ruby
-BugBunny.routes.recognize('GET', '/users/42')
-# => { controller: 'users', action: 'show', params: { 'id' => '42' }, namespace: nil }
-```
-
----
-
-### BugBunny::Controller
-
-Controllers live in the namespace configured by `config.controller_namespace` (default: `BugBunny::Controllers`).
-
-```ruby
-class UsersController < BugBunny::Controller
-  before_action :authenticate!, only: [:create, :update, :destroy]
-  after_action  :emit_audit_event, only: [:create, :update, :destroy]
-  around_action :wrap_transaction, only: [:create]
-
-  rescue_from ActiveRecord::RecordNotFound, with: :render_not_found
-
-  def index
-    render status: :ok, json: User.all
-  end
-
-  def show
-    user = User.find(params[:id])
-    render status: :ok, json: user
-  end
-
-  def create
-    user = User.new(user_params)
-    if user.save
-      render status: :created, json: user
-    else
-      render status: :unprocessable_entity, json: { errors: user.errors }
-    end
-  end
-
-  private
-
-  def authenticate!
-    render status: :unauthorized, json: { error: 'Unauthorized' } unless valid_token?
-  end
-
-  def render_not_found(e)
-    render status: :not_found, json: { error: e.message }
-  end
-end
-```
-
-**`render` signature:**
-```ruby
-render(status:, json: nil, headers: {})
-# status: HTTP symbol (:ok, :created, :not_found, ...) or Integer
-# headers: merged into response_headers — received by on_rpc_reply
-```
-
-**`params`** — `HashWithIndifferentAccess` containing:
-- Query string parameters
-- `:id` extracted from the route
-- JSON body (parsed automatically if `content_type` includes `json`)
-
-**`raw_string`** — the unparsed body when content type is not JSON.
-
-**`self.call(headers:, body:)`** — entry point called by the Consumer; returns `{ status:, headers:, body: }`.
-
----
-
-### BugBunny::Resource
-
-```ruby
-class Order < BugBunny::Resource
-  self.exchange      = 'orders_exchange'
-  self.exchange_type = 'direct'
-  self.routing_key   = 'orders'
-
-  attribute :id,     :integer
-  attribute :status, :string
-  attribute :total,  :float
-
-  validates :status, presence: true
-
-  before_save :set_defaults
-end
-```
-
-**Class methods:**
-
-| Method | HTTP | Description |
-|---|---|---|
-| `find(id)` | GET `resource/id` | Returns instance or `nil` on 404 |
-| `where(filters)` | GET `resource` | Returns Array, empty on 404 |
-| `all` | GET `resource` | Alias for `where({})` |
-| `create(attrs)` | POST `resource` | Returns instance (may have errors) |
-
-**Instance methods:**
-
-| Method | HTTP | Description |
-|---|---|---|
-| `save` | POST or PUT | POST if new, PUT if persisted. Returns Boolean. |
-| `update(attrs)` | PUT | `assign_attributes` + `save` |
-| `destroy` | DELETE | Returns Boolean |
-| `persisted?` | — | True after successful save or find |
-| `changed?` | — | True if typed or dynamic attributes changed |
-
-**`.with` — per-call context override:**
-```ruby
-# Block form (thread-safe, restores context after block)
-Order.with(exchange: 'other_exchange') do
-  Order.find(1)
-end
-
-# Single-call proxy (single-use, raises on second call)
-Order.with(routing_key: 'vip_orders').where(status: 'pending')
-```
-
-**Class-level config:**
-```ruby
-Order.connection_pool  = MY_POOL
-Order.exchange         = 'orders_exchange'
-Order.exchange_type    = 'direct'
-Order.routing_key      = 'orders'
-Order.resource_name    = 'orders'      # default: class name pluralized/underscored
-Order.param_key        = 'order'       # default: model_name.element
-Order.exchange_options = { durable: true }
-Order.queue_options    = { durable: true }
-```
-
----
-
-### BugBunny::Client
-
-For cases where `Resource` is too high-level:
-
-```ruby
-client = BugBunny::Client.new(pool: MY_POOL) do |stack|
-  stack.use MyTracingMiddleware
-  stack.use BugBunny::Middleware::RaiseError
-  stack.use BugBunny::Middleware::JsonResponse
-end
-
-# RPC (blocking)
-response = client.request('users/1',
-  method: :get,
-  exchange: 'users_exchange',
-  exchange_type: 'direct',
-  routing_key: 'users'
-)
-
-# Fire-and-forget
-client.publish('events',
-  method: :post,
-  exchange: 'events_exchange',
-  routing_key: 'events',
-  body: { type: 'user.created', user_id: 42 }
-)
-```
-
----
-
-### BugBunny::ConsumerMiddleware
-
-```ruby
-# Register globally
-BugBunny.consumer_middlewares.use MyMiddleware
-
-# Or via configuration
-BugBunny.configure do |config|
-  config.consumer_middlewares.use TracingMiddleware
-end
-```
-
-**Writing a middleware:**
-```ruby
-class MyMiddleware
-  def initialize(app)
-    @app = app
-  end
-
-  def call(delivery_info, properties, body)
-    # before
-    @app.call(delivery_info, properties, body)
-    # after
-  end
-end
-```
-
----
-
-### BugBunny.create_connection
-
-```ruby
-conn = BugBunny.create_connection   # Returns a connected Bunny::Session
-```
-
-Used to populate a `ConnectionPool`:
-```ruby
-MY_POOL = ConnectionPool.new(size: 5, timeout: 5) { BugBunny.create_connection }
-BugBunny::Resource.connection_pool = MY_POOL
-```

data/docs/ai/architecture.md

@@ -1,92 +0,0 @@
-## Architecture
-
-### Component Map
-
-```
-Publisher side (Service A)                Consumer side (Service B)
-─────────────────────────────             ─────────────────────────────────────
-Resource.find / .where / .save            Consumer#subscribe (blocking loop)
-  └─ Client#request / #publish              └─ ConsumerMiddleware::Stack#call
-       └─ Middleware::Stack (onion)               └─ Consumer#process_message
-            └─ Producer#rpc / #fire                    └─ Router#recognize
-                 └─ Session#exchange                         └─ Controller.call
-                 └─ Bunny channel                                └─ action method
-                      └─ RabbitMQ                                └─ render(...)
-                                                           └─ Consumer#reply
-```
-
-### Session
-
-`BugBunny::Session` wraps a Bunny channel. It caches exchange and queue objects by name to avoid redundant AMQP declarations. Cache writes are protected by a `Mutex` (double-checked locking pattern). One Session per connection slot — created lazily in `Client#session_for` and stored as an ivar on the Bunny connection object.
-
-### Producer
-
-`BugBunny::Producer` publishes messages. One Producer per connection slot — cached alongside the Session. Caching is mandatory: the Producer registers a `basic_consume` on the channel to listen for Direct Reply-to responses. Creating a second Producer on the same channel would trigger an AMQP error (double-consumer).
-
-**RPC flow:**
-1. `Producer#rpc` assigns a `correlation_id` and publishes with `reply_to: 'amq.rabbitmq.reply-to'`.
-2. A `Concurrent::IVar` (`future`) is registered in an in-memory hash keyed by `correlation_id`.
-3. A reply-listener thread sets `future.set(payload)` when the reply arrives.
-4. The calling thread blocks on `future.value(timeout)`.
-5. On success: `on_rpc_reply&.call(headers)` is invoked, then the response is parsed.
-6. On timeout: `BugBunny::RequestTimeout` is raised.
-
-**Fire-and-forget flow:**
-`Producer#fire` publishes without `reply_to`. No blocking.
-
-### Client
-
-`BugBunny::Client` implements the Faraday-style Onion Middleware pattern. The final action in the chain is the call to `Producer#rpc` or `Producer#fire`. Middlewares wrap that action, each calling `app.call(request)` to continue the chain.
-
-Built-in middlewares for `Resource`:
-- `Middleware::RaiseError` — converts non-2xx status codes to exceptions.
-- `Middleware::JsonResponse` — parses the JSON body and normalizes the response hash.
-
-### Consumer
-
-`BugBunny::Consumer` is a blocking subscribe loop intended to run in a dedicated process (not inside Puma). Responsibilities:
-1. Declare exchange, queue, and binding.
-2. Start a background `Concurrent::TimerTask` as a health check.
-3. For each message: invoke `ConsumerMiddleware::Stack`, then `process_message`.
-
-`process_message` flow:
-1. Extract `path` from `properties.type` (or `headers['path']`).
-2. Extract HTTP method from `headers['x-http-method']`.
-3. Parse query string from the path.
-4. Call `BugBunny.routes.recognize(method, path)` → controller + action + params.
-5. Constantize the controller class; verify it inherits from `BugBunny::Controller` (RCE prevention).
-6. Call `ControllerClass.call(headers:, body:)` → response hash.
-7. If `reply_to` is present: publish reply with `rpc_reply_headers` injected.
-8. ACK the delivery tag.
-
-On any error: publish a 500 reply (so the RPC caller doesn't timeout), then NACK/reject.
-
-### ConsumerMiddleware::Stack
-
-A pipeline of middleware objects. Registration is protected by a `Mutex`. Each middleware is a class implementing `#initialize(app)` and `#call(delivery_info, properties, body)`. The terminal app is the controller dispatch lambda. Middlewares run in registration order (first registered = outermost wrapper).
-
-### Router
-
-`BugBunny::Routing::RouteSet` stores an array of `Route` objects. `recognize(method, path)` iterates routes looking for a match. Routes are registered via the DSL:
-- `resources :users` → 5 standard routes (index, show, create, update, destroy) + member/collection.
-- `namespace :admin { resources :users }` → same routes with path prefix `admin/` and namespace `Admin::Controllers`.
-
-### Resource
-
-`BugBunny::Resource` is an ActiveModel class. It resolves AMQP config (exchange, routing key, pool) via a 3-level cascade: thread-local (set by `.with`) → class-level → superclass. Dirty tracking covers both typed `attribute` columns (via ActiveModel::Dirty) and dynamic attributes (via `@extra_attributes` + `@dynamic_changes`).
-
-### Configuration Cascade (Resource)
-
-```
-Thread.current["bb_#{object_id}_exchange"]   ← .with(exchange:) sets this
-  ↓ (nil fallback)
-Resource.exchange=                            ← class-level static config
-  ↓ (nil fallback)
-ParentResource.exchange=                      ← walks superclass chain
-```
-
-Same cascade for: `routing_key`, `exchange_type`, `pool`, `exchange_options`, `queue_options`.
-
-### Observability
-
-All BugBunny classes include `BugBunny::Observability`. `safe_log` formats structured log lines as `component=x event=clase.evento [key=value ...]` and filters sensitive keys (`password`, `token`, `secret`, `api_key`, `auth`, etc.). Log failures are swallowed — they never affect the main flow.

data/docs/ai/errors.md

@@ -1,158 +0,0 @@
-## Errors
-
-All BugBunny exceptions inherit from `BugBunny::Error < StandardError`. Catch `BugBunny::Error` to handle all gem-level errors.
-
----
-
-### BugBunny::ConfigurationError
-
-**Cause:** `BugBunny.configure` block completed with invalid values. Triggered by `validate!` at the end of `configure`.
-
-**Common triggers:**
-- `host` is nil or empty string
-- `port` is outside `1..65535`
-- `rpc_timeout` is not an Integer or is outside `1..3600`
-
-**How to reproduce:**
-```ruby
-BugBunny.configure { |c| c.host = '' }
-# => BugBunny::ConfigurationError: host is required
-```
-
-**Resolution:** Check all required fields. See `Configuration::VALIDATIONS` for the full list of validated attributes and their constraints.
-
----
-
-### BugBunny::CommunicationError
-
-**Cause:** TCP-level failure connecting to or communicating with RabbitMQ. Usually wraps a Bunny internal exception.
-
-**Common triggers:**
-- RabbitMQ is not running
-- Wrong host/port
-- Firewall blocking the connection
-- Network interruption during message exchange
-
-**Resolution:** Check RabbitMQ is reachable (`telnet host 5672`). Review `network_recovery_interval` and `max_reconnect_attempts` settings. The Consumer retries automatically with exponential backoff.
-
----
-
-### BugBunny::SecurityError
-
-**Cause:** The Consumer received a message with a `type` header that resolves to a class not inheriting from `BugBunny::Controller`.
-
-**How to reproduce:**
-```ruby
-# Publish a message with type: "Kernel"
-```
-
-**Resolution:** This is an intentional RCE prevention check. Ensure all controller classes inherit from `BugBunny::Controller`. If legitimate, verify `config.controller_namespace` is set correctly.
-
----
-
-### BugBunny::RequestTimeout
-
-**Cause:** An RPC call did not receive a reply within `config.rpc_timeout` seconds.
-
-**Common triggers:**
-- The Consumer is not running
-- The Consumer is overwhelmed (increase `channel_prefetch`)
-- `rpc_timeout` is too low for the workload
-- The remote controller raised an exception before sending a reply (check consumer logs)
-
-**Resolution:** Check that the Consumer process is alive. Review `consumer.execution_error` log entries on the consumer side. Increase `rpc_timeout` if the operation is legitimately slow.
-
----
-
-### BugBunny::NotFound (404)
-
-**Cause:** The remote service responded with HTTP 404. Raised by `Middleware::RaiseError`.
-
-**In Resource context:** `find` and `where` catch this internally and return `nil` / `[]` respectively.
-
-**In Client context:** Propagates unless caught by the caller.
-
-**Resolution:** Verify the resource ID exists. Ensure the Consumer's route for that path is registered.
-
----
-
-### BugBunny::BadRequest (400)
-
-**Cause:** The remote service returned 400. Also raised locally if the JSON body cannot be parsed.
-
-**Local trigger:**
-```ruby
-# In Controller#prepare_params — body is not valid JSON and content_type includes 'json'
-```
-
-**Resolution:** Verify the request body is valid JSON when `content_type: 'application/json'` is used.
-
----
-
-### BugBunny::Conflict (409)
-
-**Cause:** The remote service returned 409 — the request is technically valid but conflicts with business rules or existing data.
-
-**Resolution:** Handle the conflict in application logic. Inspect `e.message` for details from the remote service.
-
----
-
-### BugBunny::UnprocessableEntity (422)
-
-**Cause:** The remote service returned 422 (validation failure).
-
-**Attributes:**
-- `e.error_messages` — `Hash`, `Array`, or `String` extracted from `{ "errors": ... }` in the response body.
-- `e.raw_response` — The raw response body.
-
-**In Resource context:** `save` catches this, loads errors into `resource.errors`, and returns `false`.
-
-**In Client context:** Raised directly.
-
-**Resolution:**
-```ruby
-resource = Order.create(attrs)
-unless resource.persisted?
-  resource.errors.full_messages  # => ["Status can't be blank"]
-end
-```
-
----
-
-### BugBunny::NotAcceptable (406)
-
-**Cause:** The remote service returned 406 — it cannot produce a response matching the requested content type.
-
-**Resolution:** Ensure the client and server agree on content type. BugBunny uses `application/json` by default.
-
----
-
-### BugBunny::InternalServerError (500)
-
-**Cause:** The remote service returned 500. Also sent by the Consumer when an unhandled exception occurs during `process_message`.
-
-**Resolution:** Check `consumer.execution_error` log entries on the consumer side for the actual exception. Fix the underlying error in the controller.
-
----
-
-### BugBunny::Error: "Connection pool missing for ClassName"
-
-**Cause:** `Resource.bug_bunny_client` was called before `Resource.connection_pool` was set.
-
-**Resolution:** Set `BugBunny::Resource.connection_pool = MY_POOL` in the initializer before any Resource calls.
-
----
-
-### BugBunny::Error: "ScopeProxy is single-use"
-
-**Cause:** A `ScopeProxy` returned by `.with(...)` without a block was called more than once.
-
-**Resolution:** Use the block form: `Resource.with(...) { ... }` or call `.with(...)` again for each subsequent call.
-
----
-
-### BugBunny::Error: "Exchange not defined for ClassName"
-
-**Cause:** `Resource.current_exchange` was called but no exchange was configured at any level (thread-local, class, or superclass).
-
-**Resolution:** Set `self.exchange = 'exchange_name'` in the Resource class definition or use `.with(exchange:)`.

data/docs/ai/faq_external.md

@@ -1,133 +0,0 @@
-## FAQ — External (Integrator / Consumer of BugBunny)
-
-### How do I set up BugBunny in a Rails app?
-
-Add to Gemfile: `gem 'bug_bunny'` and `gem 'connection_pool'`. Run `rails generate bug_bunny:install`. Edit `config/initializers/bug_bunny.rb` with your RabbitMQ credentials. Create a pool: `MY_POOL = ConnectionPool.new(size: 5) { BugBunny.create_connection }`. Assign it: `BugBunny::Resource.connection_pool = MY_POOL`. See `docs/howto/rails.md` for the complete setup.
-
----
-
-### How do I make an RPC call (blocking request)?
-
-Use `Resource.find` / `Resource.where` / `Resource.create` — they all do RPC internally. For lower-level control: `client.request('users/1', method: :get, exchange: 'users_exchange', routing_key: 'users')`. The call blocks until the remote service replies or `rpc_timeout` expires.
-
----
-
-### How do I publish without waiting for a reply?
-
-Use `client.publish('events', method: :post, exchange: 'events_exchange', routing_key: 'events', body: { ... })`. Fire-and-forget — does not block. No RPC timeout applies.
-
----
-
-### What happens when `find` returns nil vs raises?
-
-`Resource.find` returns `nil` on 404 (does not raise). `Resource.where` returns `[]` on 404. Both raise `BugBunny::RequestTimeout` if the remote service does not reply within `rpc_timeout`. They raise `BugBunny::ServerError` on 5xx responses.
-
----
-
-### How do I handle validation errors from the remote service?
-
-`resource.save` returns `false` on 422 and loads the remote errors into `resource.errors`. Check `resource.valid?` then `resource.errors.full_messages`. The remote service must render `{ errors: { field: ['message'] } }` for the errors to be auto-loaded.
-
----
-
-### How do I use `.with` to override the exchange per call?
-
-```ruby
-# Block form (preferred — thread-safe, restores after block)
-Order.with(exchange: 'priority_exchange', routing_key: 'priority') do
-  Order.find(id)
-end
-
-# Single-call proxy
-Order.with(exchange: 'priority_exchange').find(id)
-# ScopeProxy is single-use — calling a second method raises BugBunny::Error
-```
-
----
-
-### How do I define a Resource with typed attributes?
-
-```ruby
-class User < BugBunny::Resource
-  self.exchange = 'users_exchange'
-
-  attribute :id,    :integer
-  attribute :name,  :string
-  attribute :email, :string
-
-  validates :name, presence: true
-end
-```
-
-Typed attributes get ActiveModel coercion and dirty tracking. Attributes not declared with `attribute` are handled dynamically via `method_missing` and tracked in `@extra_attributes`.
-
----
-
-### How do I add client-side middleware to a Resource?
-
-```ruby
-class Order < BugBunny::Resource
-  client_middleware do |stack|
-    stack.use MyRetryMiddleware
-  end
-end
-```
-
-Middlewares are inherited by subclasses and applied in registration order (first = outermost). `RaiseError` and `JsonResponse` are always added as the innermost middlewares by `Resource` — do not add them manually.
-
----
-
-### How do I run the Consumer in a Rails app?
-
-The Consumer is a blocking loop. Run it in a separate process, not inside Puma:
-
-```ruby
-# lib/tasks/rabbit.rake
-task consumer: :environment do
-  conn = BugBunny.create_connection
-  consumer = BugBunny::Consumer.new(conn)
-  trap('TERM') { consumer.shutdown; exit }
-  trap('INT')  { consumer.shutdown; exit }
-  consumer.subscribe(
-    queue_name: 'my_queue', exchange_name: 'my_exchange', routing_key: 'my_key'
-  )
-end
-```
-
----
-
-### How do I write a Controller?
-
-Subclass `BugBunny::Controller`. Place it in the namespace from `config.controller_namespace` (default: `BugBunny::Controllers`). Implement action methods (`index`, `show`, `create`, `update`, `destroy` or custom). Call `render(status:, json:)` to respond. The Consumer routes messages to `YourController.call(headers:, body:)`.
-
----
-
-### How do I propagate trace context through RabbitMQ?
-
-On the consumer side, inject headers into replies:
-```ruby
-config.rpc_reply_headers = -> { { 'X-Trace-Id' => Tracer.current } }
-```
-On the producer side, hydrate context from the reply:
-```ruby
-config.on_rpc_reply = ->(headers) { Tracer.hydrate(headers['X-Trace-Id']) }
-```
-For consumer-side middleware (propagating from incoming request), use `ConsumerMiddleware`.
-
----
-
-### How do I configure health checks for Kubernetes?
-
-Set `config.health_check_file = '/app/tmp/bug_bunny_health'`. BugBunny touches that file every `health_check_interval` seconds (default: 60) after verifying the RabbitMQ connection. Add a `livenessProbe` in your Kubernetes manifest checking for that file's existence.
-
----
-
-### What is the default RPC timeout and how do I change it?
-
-Default: 10 seconds. Override globally: `config.rpc_timeout = 30`. Override per request: `client.request('users/1', method: :get, exchange: ..., timeout: 5)`. When exceeded, `BugBunny::RequestTimeout` is raised.
-
----
-
-### Do I need to declare exchanges and queues manually?
-
-No. BugBunny declares them automatically when `subscribe` (consumer) or the first RPC call (producer) is made. Use `config.exchange_options` and `config.queue_options` for global defaults (e.g., `{ durable: true }`). Override per resource with `Resource.exchange_options=` or per call with `.with(exchange_options:)`.