bug_bunny 4.6.1 → 4.8.0

data/docs/ai/antipatterns.md

@@ -0,0 +1,166 @@
+## Antipatterns
+
+### Running Producer and Consumer in the same process thread
+
+**Wrong:**
+```ruby
+# In the same Puma process
+Thread.new { BugBunny::Consumer.new(conn).subscribe(..., block: true) }
+BugBunny::Resource.find(1)   # uses a different connection slot — works but is wrong architecturally
+```
+
+**Why it's wrong:** The Consumer is a blocking loop designed to run in a dedicated worker process. Running it inside Puma wastes threads and ties service lifetime to the web server. If the web server restarts, the consumer dies too.
+
+**Correct:** Run the Consumer as a separate process (Rake task, separate container/Dockerfile).
+
+---
+
+### Creating a new Client or Producer per request
+
+**Wrong:**
+```ruby
+def show
+  client = BugBunny::Client.new(pool: MY_POOL)  # new client on every request
+  client.request(...)
+end
+```
+
+**Why it's wrong:** `Client` itself is cheap, but creating it with a block configures a new middleware stack. More importantly, if you bypass `Resource` and call `Producer` directly, creating a new `Producer` on an already-used channel causes an AMQP `basic_consume` conflict.
+
+**Correct:** Use `Resource` (which caches Client → Session → Producer per connection slot) or create the `Client` once at application boot.
+
+---
+
+### Setting `Resource.connection_pool` inside a request
+
+**Wrong:**
+```ruby
+class OrdersController < ApplicationController
+  def index
+    BugBunny::Resource.connection_pool = ConnectionPool.new(...) { BugBunny.create_connection }
+    Order.all
+  end
+end
+```
+
+**Why it's wrong:** The pool is a global class-level setting. Reassigning it in a request creates a race condition and leaks connections.
+
+**Correct:** Set `connection_pool` once in the initializer at boot.
+
+---
+
+### Calling `.with` proxy more than once
+
+**Wrong:**
+```ruby
+scope = Order.with(exchange: 'priority')
+scope.find(1)
+scope.find(2)   # raises BugBunny::Error — ScopeProxy is single-use
+```
+
+**Why it's wrong:** `ScopeProxy#method_missing` sets `@used = true` on the first call. A second call raises.
+
+**Correct:** Use the block form of `.with` for multiple calls within the same scope:
+```ruby
+Order.with(exchange: 'priority') do
+  Order.find(1)
+  Order.find(2)
+end
+```
+
+---
+
+### Adding `RaiseError` or `JsonResponse` manually to a Resource middleware stack
+
+**Wrong:**
+```ruby
+class Order < BugBunny::Resource
+  client_middleware do |stack|
+    stack.use BugBunny::Middleware::RaiseError    # already added by Resource
+    stack.use BugBunny::Middleware::JsonResponse  # already added by Resource
+  end
+end
+```
+
+**Why it's wrong:** `Resource#bug_bunny_client` always adds `RaiseError` and `JsonResponse` as the innermost middlewares. Adding them again wraps the response in a second parsing pass, causing errors.
+
+**Correct:** Only add custom middlewares in `client_middleware`. Never add the built-ins.
+
+---
+
+### Calling `render` multiple times in an action or filter
+
+**Wrong:**
+```ruby
+def show
+  render status: :ok, json: user
+  render status: :not_found, json: { error: 'Not found' }  # second render — first one wins
+end
+```
+
+**Why it's wrong:** The second `render` call overwrites `@rendered_response`. Behavior is undefined and dependent on execution order.
+
+**Correct:** Use early returns or `return render(...)` to ensure only one render is called.
+
+---
+
+### Raising exceptions from `rpc_reply_headers` or `on_rpc_reply`
+
+**Wrong:**
+```ruby
+config.rpc_reply_headers = -> { { 'X-Trace-Id' => Tracer.header! } }  # Tracer.header! may raise
+```
+
+**Why it's wrong:** An exception in `rpc_reply_headers` propagates into the Consumer's `reply` method, corrupting the RPC reply and causing the caller to timeout.
+
+**Correct:** Wrap the proc body in a rescue:
+```ruby
+config.rpc_reply_headers = -> { { 'X-Trace-Id' => (Tracer.header rescue nil) } }
+```
+
+---
+
+### Declaring exchanges with incompatible options after first declaration
+
+**Wrong:**
+```ruby
+# Service A declares exchange as non-durable
+BugBunny.configure { |c| c.exchange_options = { durable: false } }
+
+# Service B (or a later boot) declares the same exchange as durable
+BugBunny.configure { |c| c.exchange_options = { durable: true } }
+```
+
+**Why it's wrong:** RabbitMQ raises a channel error (406 PRECONDITION_FAILED) if you try to redeclare an exchange with different attributes. This crashes the channel.
+
+**Correct:** Agree on exchange options across all services. Use `{ durable: true }` in all production services.
+
+---
+
+### Using `Resource` without a connection pool
+
+**Wrong:**
+```ruby
+Order.find(1)  # BugBunny::Error: Connection pool missing for Order
+```
+
+**Why it's wrong:** `Resource.bug_bunny_client` raises if `connection_pool` is nil.
+
+**Correct:** Always set `BugBunny::Resource.connection_pool` (or a subclass-specific pool) before making calls. Do this in the initializer.
+
+---
+
+### Calling `logger.debug "..."` directly inside BugBunny classes
+
+**Wrong:**
+```ruby
+logger.debug "Processing #{message}"  # eager interpolation, ignores debug level
+```
+
+**Why it's wrong:** String interpolation happens regardless of log level, wasting CPU. Also bypasses `safe_log`'s sensitive key filtering.
+
+**Correct:**
+```ruby
+safe_log(:debug, 'component.event', key: value)
+# safe_log passes blocks to logger.debug { ... } internally
+```

data/docs/ai/api.md

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

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

@@ -0,0 +1,158 @@
+## 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:)`.