bug_bunny 4.8.0 → 4.8.1

data/docs/ai/faq_internal.md

@@ -1,86 +0,0 @@
-## FAQ — Internal (Maintainer / Developer of BugBunny)
-
-### Why is Producer cached per connection slot instead of instantiated per request?
-
-`Producer#initialize` calls `channel.basic_consume` on the `amq.rabbitmq.reply-to` pseudo-queue to listen for RPC replies. Creating a second `basic_consume` on the same channel raises an AMQP error. Therefore, one Producer per channel (= per connection slot) is mandatory. The cache is stored as `@_bug_bunny_producer` ivar on the Bunny connection object, which is safe because `ConnectionPool` guarantees each slot is used by one thread at a time.
-
----
-
-### Why is Session cached per connection slot?
-
-Same reason as Producer — and the Session wraps the channel. Recreating a Session would create a new channel and invalidate the cached exchange/queue objects. Caching is stored as `@_bug_bunny_session` on the Bunny connection object.
-
----
-
-### How does the Session handle thread safety for exchange/queue declarations?
-
-Session uses a double-checked locking pattern with a `Mutex` for its caches (`@exchange_cache`, `@queue_cache`). The read path (fast path) checks without locking; the write path acquires the mutex and checks again before writing. This avoids redundant AMQP declarations without making every read a mutex acquisition.
-
----
-
-### Why does Resource have two dirty tracking mechanisms?
-
-ActiveModel::Dirty only tracks attributes declared with `attribute :name, :type`. BugBunny Resources allow dynamic attributes (unknown at class definition time) stored in `@extra_attributes`. These are tracked manually via `@dynamic_changes` (a `Set`). The `changed?` and `changed` methods merge both to produce a unified change list.
-
----
-
-### How does the 3-level config cascade work in Resource?
-
-`resolve_config(key, instance_var)` checks in order:
-1. `Thread.current["bb_#{object_id}_#{key}"]` — set by `.with(...)`.
-2. `self.instance_variable_get(instance_var)` — class-level static config.
-3. Walk `superclass` chain up to (but not including) `BugBunny::Resource`.
-
-This means a subclass can override the parent's config, and `.with` overrides everything for the duration of its block.
-
----
-
-### How does ConsumerMiddleware::Stack protect against concurrent registration?
-
-`Stack#use` wraps the append in a `@mutex.synchronize` block. The execution path (`call`) does not use the mutex — it reads `@middlewares` once at call time (snapshot). This is safe because Rails/Zeitwerk loads middleware registrations at boot, before any concurrent requests.
-
----
-
-### How does routing with namespaces work internally?
-
-`namespace :admin { resources :users }` generates `Route` objects with:
-- `path_prefix: 'admin'` — prepended to the path pattern.
-- `namespace: 'Admin::Controllers'` — overrides the default namespace for `constantize`.
-
-In `process_message`, the Consumer resolves `base_namespace = route_info[:namespace] || config.controller_namespace` before calling `constantize`.
-
----
-
-### What is the RCE prevention in the Consumer?
-
-After `constantize`, the Consumer checks `controller_class < BugBunny::Controller`. This prevents an attacker from crafting a message with a `type` header pointing to an arbitrary Ruby class (e.g., `Kernel` or `File`) and triggering its methods. Any class not inheriting from `BugBunny::Controller` gets a 403 reply and the message is rejected.
-
----
-
-### How does `before_action` halt chain propagation?
-
-`run_before_actions` iterates before-actions and calls each. After each call, it checks `rendered_response`. If a filter called `render(...)`, `@rendered_response` is set. The method returns `false`, and `core_execution` skips the action and `after_actions`. After-actions do not run if the before-action chain was halted.
-
----
-
-### How does `after_action` differ from `around_action`?
-
-`after_action` runs after the action method returns, but only if no `before_action` halted the chain and no exception was raised. `around_action` wraps the entire execution including before/after actions and is responsible for yielding. Use `around_action` when you need cleanup regardless of exceptions.
-
----
-
-### How does `safe_log` prevent log failures from affecting main flow?
-
-`safe_log` wraps every logger call in `rescue StandardError`. It also filters sensitive keys by checking if the key string matches a predefined set of patterns (`password`, `pass`, `passwd`, `secret`, `token`, `api_key`, `auth`) before emitting values. Blocks are always passed to `logger.debug` to avoid string interpolation cost at non-debug levels.
-
----
-
-### How is the Consumer health check implemented?
-
-`start_health_check` creates a `Concurrent::TimerTask` that runs every `health_check_interval` seconds. Each tick calls `channel.queue_declare(queue_name, passive: true)` — a passive declare that verifies the queue exists without creating it. On failure, it calls `session.close`, which triggers the reconnect loop in `subscribe`. The health file is touched on success.
-
----
-
-### What triggers the reconnect loop in Consumer?
-
-Any `StandardError` raised inside the `subscribe` rescue block. The loop uses exponential backoff: `wait = [interval * 2^(attempt-1), max_interval].min`. If `max_reconnect_attempts` is set and exceeded, the error is re-raised, killing the process.

data/docs/ai/glossary.md

@@ -1,45 +0,0 @@
-## Glossary
-
-**AMQP** — Advanced Message Queuing Protocol. The binary wire protocol used by RabbitMQ. BugBunny uses Bunny as its AMQP client.
-
-**Exchange** — A RabbitMQ routing point. Publishers send messages to exchanges; exchanges route them to queues based on bindings and routing keys. BugBunny supports `direct`, `topic`, and `fanout` types.
-
-**Queue** — A buffer that holds messages until they are consumed. A queue is bound to an exchange with a routing key pattern.
-
-**Routing key** — A string label attached to a published message. The exchange uses it to decide which queues receive the message. In BugBunny, the routing key defaults to the pluralized resource name (e.g., `users`).
-
-**Binding** — The link between an exchange and a queue, specifying which routing key patterns match.
-
-**Session** — `BugBunny::Session`. A wrapper around a Bunny channel. Declares exchanges and queues, caches their AMQP objects, and handles double-checked locking for thread safety.
-
-**Producer** — `BugBunny::Producer`. Publishes messages to RabbitMQ. Implements both RPC (blocking) and fire-and-forget (non-blocking) modes. One Producer is cached per connection slot.
-
-**Consumer** — `BugBunny::Consumer`. The subscribe loop that runs in a worker process. Receives messages, routes them through middleware and the router, dispatches to a controller, and sends RPC replies.
-
-**RPC (Remote Procedure Call)** — A synchronous request-response pattern over RabbitMQ. The producer publishes with `reply_to: 'amq.rabbitmq.reply-to'` and blocks on a `Concurrent::IVar` until the consumer replies to that pseudo-queue.
-
-**Fire-and-forget** — An asynchronous publish with no reply expected. The producer does not block. Used for events, notifications, and side effects.
-
-**Direct Reply-to** — A RabbitMQ pseudo-queue (`amq.rabbitmq.reply-to`) that allows RPC replies without declaring a temporary queue. BugBunny uses this for all RPC responses.
-
-**Controller** — `BugBunny::Controller`. A class that handles an incoming routed message. Mirrors Rails ActionController: supports `before_action`, `around_action`, `after_action`, `rescue_from`, `params`, and `render`.
-
-**Resource** — `BugBunny::Resource`. An ActiveRecord-like ORM over AMQP. Wraps CRUD operations as RPC calls. Used by the publishing side to interact with a remote service.
-
-**Client** — `BugBunny::Client`. High-level API for the publisher side. Implements the Onion Middleware (Faraday-style) pattern around the Producer.
-
-**ConsumerMiddleware** — A pipeline of middleware objects that runs before each message is dispatched to a controller. Used for cross-cutting concerns: tracing, authentication, logging.
-
-**ConnectionPool** — A `connection_pool` gem pool of Bunny connections. Each slot holds one connection, one Session, and one Producer. `Resource.connection_pool` must be set before making AMQP calls.
-
-**IVar (Ivar / Concurrent::IVar)** — An immutable variable from the `concurrent-ruby` gem. Used to block the calling thread until the RPC reply arrives or the timeout expires.
-
-**health_check_file** — A file path that BugBunny touches periodically (every `health_check_interval` seconds) after verifying the RabbitMQ connection. Used as a liveness probe in Docker/Kubernetes.
-
-**rpc_reply_headers** — A `Proc` returning a `Hash` of AMQP headers injected into every RPC reply. Used to propagate trace context from consumer back to producer.
-
-**on_rpc_reply** — A `Proc` called on the producer's thread when an RPC reply arrives, with the reply's AMQP headers. Used to hydrate trace context in the calling service.
-
-**Namespace routing** — A DSL feature that prefixes a group of routes with a module namespace and a path prefix. Example: `namespace :admin` generates routes under `Admin::Controllers::*Controller` with path prefix `admin/`.
-
-**param_key** — The root key used to wrap the payload in POST/PUT requests. Defaults to the singularized resource name (e.g., `user` for `UsersResource`).

data/docs/concepts.md

@@ -1,140 +0,0 @@
-# Concepts
-
-## What is BugBunny?
-
-BugBunny is a Ruby gem that implements a RESTful routing layer over AMQP (RabbitMQ). It lets microservices communicate through RabbitMQ using familiar HTTP-like patterns: verbs (GET, POST, PUT, DELETE), controllers, declarative routes, synchronous RPC, and fire-and-forget publishing.
-
-**Problem it solves:** Direct HTTP coupling between microservices creates a tight dependency graph — if Service B is down, Service A fails immediately. RabbitMQ as a message bus decouples availability, but raw AMQP APIs are low-level and verbose. BugBunny gives you the ergonomics of a web framework on top of the reliability of a message broker.
-
----
-
-## AMQP in 5 Minutes
-
-AMQP (Advanced Message Queuing Protocol) is the protocol RabbitMQ implements. The key concepts:
-
-**Exchange** — Receives messages from producers and routes them to queues based on rules. Types:
-- `direct` — Routes to queues whose binding key exactly matches the routing key.
-- `topic` — Routes using wildcard patterns (`orders.*`, `#.error`).
-- `fanout` — Broadcasts to all bound queues regardless of routing key.
-
-**Queue** — Stores messages until a consumer picks them up. Durable queues survive broker restarts.
-
-**Routing Key** — A string the producer attaches to the message. The exchange uses it to decide which queues receive the message.
-
-**Binding** — A link between an exchange and a queue, optionally with a routing key pattern.
-
-In BugBunny, the **path** of the message (e.g., `nodes/123`) travels inside the AMQP `type` header. The routing key determines *which service* receives the message; the path determines *which controller and action* handles it inside that service.
-
----
-
-## Architecture
-
-```
-Service A (Producer)
-  BugBunny::Resource.find(id)
-  BugBunny::Client#request(path)
-        |
-        v
-  BugBunny::Producer
-        |  publishes to exchange with:
-        |    routing_key: 'nodes'
-        |    type header: 'nodes/123'
-        |    reply_to:    'amq.rabbitmq.reply-to'  (RPC only)
-        |    correlation_id: 'abc-123'              (RPC only)
-        v
-   [ RabbitMQ Exchange ]
-        |
-        v
-   [ RabbitMQ Queue ]
-        |
-        v
-Service B (Consumer)
-  BugBunny::Consumer (subscribe loop)
-        |
-        v
-  ConsumerMiddleware::Stack
-  (tracing, auth, etc.)
-        |
-        v
-  Router (BugBunny.routes)
-  matches 'GET nodes/123' → NodesController#show
-        |
-        v
-  NodesController#show
-  render status: :ok, json: node
-        |
-        v  (RPC only)
-  reply → amq.rabbitmq.reply-to
-        |
-        v
-Service A (unblocked)
-  future.value → { body: {...}, headers: {...} }
-```
-
----
-
-## RPC vs Fire-and-Forget
-
-BugBunny supports two communication patterns. Choosing the right one matters for system design.
-
-### Synchronous RPC (`:rpc`)
-
-The producer blocks until the consumer replies. Uses RabbitMQ's `amq.rabbitmq.reply-to` pseudo-queue — no temporary queues are created.
-
-```ruby
-response = client.request('users/42', method: :get)
-# blocks here until the consumer sends back a reply (or timeout)
-```
-
-**Use when:** Service A needs the result to continue. Example: fetching user data before building a response, validating inventory before placing an order.
-
-**Timeout:** Configurable via `config.rpc_timeout`. Raises `BugBunny::RequestTimeout` if the consumer does not reply in time.
-
-**Cost:** Ties up a thread in Service A for the duration of the call.
-
-### Fire-and-Forget (`:publish`)
-
-The producer publishes and continues immediately. No reply is expected or waited for.
-
-```ruby
-client.publish('events', body: { type: 'order.placed', order_id: 99 })
-# returns immediately with { 'status' => 202 }
-```
-
-**Use when:** Service A does not need a result. Example: emitting audit events, triggering background jobs, sending notifications.
-
-**Cost:** None — but you have no confirmation that the message was processed successfully.
-
----
-
-## Key Components
-
-| Class | Role |
-|---|---|
-| `BugBunny::Configuration` | Global settings. Validates required fields on `BugBunny.configure`. |
-| `BugBunny::Session` | Wraps a Bunny channel. Declares exchanges and queues. Thread-safe with double-checked locking. |
-| `BugBunny::Producer` | Publishes messages. Implements RPC with `Concurrent::IVar`. |
-| `BugBunny::Client` | High-level publisher API. Manages a connection pool and middleware stack. |
-| `BugBunny::Consumer` | Subscribe loop. Routes messages to controllers via `BugBunny.routes`. |
-| `BugBunny::ConsumerMiddleware::Stack` | Pipeline of middlewares executed before `process_message`. |
-| `BugBunny::Controller` | Base class for message handlers. Supports `before_action`, `after_action`, `around_action`, `rescue_from`. |
-| `BugBunny::Resource` | ActiveRecord-like ORM over AMQP. Provides `find`, `where`, `create`, `save`, `destroy`. |
-| `BugBunny::Routing::RouteSet` | Stores and matches declared routes. |
-| `BugBunny::Observability` | Mixin for structured logging. `safe_log` never raises. |
-
----
-
-## Connection Pool
-
-BugBunny uses the `connection_pool` gem to share connections safely across threads (Puma workers, Sidekiq threads).
-
-```
-ConnectionPool
-  slot 0: Bunny::Session → BugBunny::Session → BugBunny::Producer
-  slot 1: Bunny::Session → BugBunny::Session → BugBunny::Producer
-  slot N: ...
-```
-
-Each pool slot caches its `Session` and `Producer` for the lifetime of the slot. This avoids re-creating AMQP channels (expensive) and prevents the double `basic_consume` error that would occur if a new Producer were created on a reused channel.
-
-Thread safety is guaranteed by `ConnectionPool` itself: each slot is used by one thread at a time, so no additional mutex is needed at the Session or Producer level.

data/docs/howto/controller.md

@@ -1,194 +0,0 @@
-# Controllers
-
-Controllers receive routed messages and produce responses. They follow the same lifecycle as ActionController in Rails.
-
-## Defining a Controller
-
-```ruby
-module BugBunny
-  module Controllers
-    class NodesController < BugBunny::Controller
-      def index
-        nodes = Node.all
-        render status: :ok, json: nodes.map(&:as_json)
-      end
-
-      def show
-        node = Node.find(params[:id])
-        render status: :ok, json: node.as_json
-      end
-
-      def create
-        node = Node.new(node_params)
-        if node.save
-          render status: :created, json: node.as_json
-        else
-          render status: :unprocessable_entity, json: { errors: node.errors }
-        end
-      end
-    end
-  end
-end
-```
-
-The controller namespace defaults to `BugBunny::Controllers`. Override it globally with `config.controller_namespace`, or per route group with `namespace` blocks in the DSL.
-
----
-
-## params
-
-`params` merges path parameters, query string parameters, and body parameters into a single `HashWithIndifferentAccess`:
-
-```ruby
-# Message for PUT nodes/42?verbose=true with body { "node": { "status": "active" } }
-params[:id]            # => "42"        (from path)
-params[:verbose]       # => "true"      (from query string)
-params[:node][:status] # => "active"    (from JSON body)
-```
-
-Use strong-parameters style to extract what you need:
-
-```ruby
-def node_params
-  params.require(:node).permit(:name, :status)
-end
-```
-
----
-
-## before_action
-
-Runs before the action. Rendering inside a `before_action` halts the chain — the action and `after_action` callbacks do not run.
-
-```ruby
-class ApplicationController < BugBunny::Controller
-  before_action :authenticate!
-  before_action :set_node, only: [:show, :update, :destroy, :drain]
-
-  private
-
-  def authenticate!
-    token = request_headers['X-Service-Token']
-    render status: :unauthorized, json: { error: 'Unauthorized' } unless valid_token?(token)
-  end
-
-  def set_node
-    @node = Node.find(params[:id])
-    render status: :not_found, json: { error: 'Not found' } unless @node
-  end
-end
-```
-
----
-
-## after_action
-
-Runs after the action completes successfully. Skipped if a `before_action` halted the chain or if the action raised an exception — same behavior as Rails.
-
-```ruby
-class NodesController < ApplicationController
-  after_action :emit_audit_event, only: [:create, :update, :destroy]
-
-  private
-
-  def emit_audit_event
-    AuditLog.record(action: action_name, node_id: params[:id], actor: current_service)
-  end
-end
-```
-
----
-
-## around_action
-
-Wraps the action. Must call `yield` to execute the inner chain.
-
-```ruby
-class NodesController < ApplicationController
-  around_action :with_distributed_lock, only: [:drain]
-
-  private
-
-  def with_distributed_lock
-    DistributedLock.acquire("node:#{params[:id]}") { yield }
-  end
-end
-```
-
----
-
-## rescue_from
-
-Catches exceptions raised during the action and maps them to responses. Handlers are inherited and can be defined in a base `ApplicationController`.
-
-```ruby
-class ApplicationController < BugBunny::Controller
-  rescue_from ActiveRecord::RecordNotFound do |e|
-    render status: :not_found, json: { error: e.message }
-  end
-
-  rescue_from ActiveRecord::RecordInvalid do |e|
-    render status: :unprocessable_entity, json: { errors: e.record.errors.full_messages }
-  end
-
-  rescue_from StandardError do |e|
-    logger.error("Unhandled error: #{e.class} — #{e.message}")
-    render status: :internal_server_error, json: { error: 'Internal server error' }
-  end
-end
-```
-
----
-
-## render
-
-```ruby
-render status: :ok,                    json: resource.as_json
-render status: :created,               json: { id: record.id }
-render status: :no_content,            json: nil
-render status: :unprocessable_entity,  json: { errors: object.errors }
-render status: :not_found,             json: { error: 'Not found' }
-```
-
-Accepts any Rack status symbol (`:ok`, `:created`, `:not_found`, etc.) or an integer status code.
-
-### Adding response headers
-
-```ruby
-# Per-response headers (merged, non-destructive)
-render status: :ok, json: data, headers: { 'X-Request-Id' => request_id }
-
-# Headers set for the lifetime of the action (accessible via response_headers)
-def show
-  response_headers['X-Cache'] = 'HIT'
-  render status: :ok, json: Node.find(params[:id]).as_json
-end
-```
-
----
-
-## Accessing AMQP headers
-
-```ruby
-def create
-  trace_id = request_headers['X-Trace-Id']
-  # ...
-end
-```
-
-`request_headers` returns the raw AMQP headers hash from `properties.headers`.
-
----
-
-## log_tags
-
-Injects contextual tags into all log lines produced within the action's execution:
-
-```ruby
-class NodesController < ApplicationController
-  log_tag { params[:id] }
-  log_tag { current_tenant }
-end
-```
-
-Works with Rails' `ActiveSupport::TaggedLogging`.

data/docs/howto/middleware_client.md

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