bug_bunny 4.7.0 → 4.8.1

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

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