bug_bunny 4.8.0 → 4.8.1

data/.claude/commands/service-ai-setup.md

@@ -1,168 +0,0 @@
-Generate or update the complete AI documentation suite for this microservice.
-
-This skill is invoked automatically by `/pr`. It can also be run standalone.
-
-The same quality standard as BugBunny's `docs/ai/` applies here — self-contained chunks, RAG-optimized, no introductory prose.
-
----
-
-## Step 1 — Discover the current state
-
-Read in order:
-1. `docs/_index.md` — if it exists, lists all files and their purpose
-2. `docs/ai/_index.md` — if it exists, current profile and file list
-3. `CLAUDE.md` — service purpose, architecture, dependencies
-4. `config/services.yml` — declared dependencies (other services this one talks to)
-5. `config/routes.rb` or `config/initializers/bug_bunny_routes.rb` — what this service exposes
-
-If `docs/ai/` does not exist yet, this is a **first-time generation**. Create from scratch.
-If it exists, **update only the sections affected by the changes in this PR**.
-
----
-
-## Step 2 — Profile
-
-Microservices always use the **full profile** with `contracts.md` instead of `api.md`:
-
-```
-docs/ai/
-  _index.md
-  glossary.md
-  architecture.md
-  contracts.md      ← what this service exposes (queues, endpoints, events)
-  faq_internal.md
-  faq_external.md
-  antipatterns.md
-  errors.md
-```
-
----
-
-## Step 3 — Analyze the codebase
-
-Read:
-- `app/` — controllers, models, workers, services
-- `config/` — routes, initializers, services.yml
-- `lib/` — custom libraries
-- `spec/` — usage patterns and edge cases
-- `CHANGELOG.md` or git log — what changed in this PR
-
----
-
-## Step 4 — Generate or update each file
-
-Apply the same RAG optimization rules as `gem-ai-setup`:
-1. Each section ≤ 400 tokens, self-contained
-2. `faq_*.md` strict Q&A format, H3 question, answer ≤ 150 words
-3. `glossary.md` one entry per term, 1-3 lines
-4. `errors.md` one entry per error, cause + reproduction + resolution
-5. No introductory prose
-
-### `_index.md`
-
-Frontmatter manifest. Use `kind: microservice` and `transports:` listing all transports used (bug_bunny, http, etc.). List every file with its audience.
-
-```yaml
----
-type: knowledge_base
-kind: microservice
-name: service_name
-version: main        # microservices don't have semver — use branch or date
-profile: full
-language: ruby
-audiences:
-  - internal
-  - external
-transports:
-  - bug_bunny        # list actual transports used
-  - http
-files:
-  - path: glossary.md
-    audience: [internal, external]
-  - path: architecture.md
-    audience: [internal]
-  - path: contracts.md
-    audience: [external]
-  ...
----
-```
-
-### `glossary.md`
-
-Domain terms specific to this service's business domain and technical patterns.
-
-### `architecture.md`
-
-Internal-facing. Include:
-- Service responsibility (one paragraph)
-- Component map
-- Data flows for the main operations
-- External dependencies and how they're used
-- Background jobs and their triggers
-
-### `contracts.md`
-
-External-facing. The complete contract this service exposes. Include:
-
-**BugBunny queues (if applicable):**
-- Queue name, exchange, routing key, exchange type
-- For each route: method, path, request format, response format, possible errors
-- Example request and response payloads
-
-**HTTP endpoints (if applicable):**
-- Method, path, parameters, response format
-- Authentication requirements
-
-**Events published (if applicable):**
-- Exchange, routing key, payload format
-
-### `faq_internal.md`
-
-Q&A for the service developer. Cover:
-- How to add a new route or endpoint
-- How background jobs work and how to add one
-- How to add a new service dependency
-- Non-obvious architectural decisions
-
-### `faq_external.md`
-
-Q&A for developers of other services that consume this one. Cover:
-- How to make a request to this service
-- What errors to expect and how to handle them
-- How to handle retries and timeouts
-- How to test integrations against this service
-
-### `antipatterns.md`
-
-Common mistakes when interacting with or modifying this service.
-
-### `errors.md`
-
-All error responses this service can return. For each:
-- HTTP status / error code
-- When it occurs
-- What the response body looks like
-- How the caller should handle it
-
----
-
-## Step 5 — Update docs/howto/ and README.md
-
-Read `docs/_index.md` to discover which human docs exist.
-Update sections affected by this PR's changes.
-Update `README.md` last — after `docs/howto/` is updated.
-
-README structure for a microservice:
-1. Service purpose (one paragraph)
-2. Transports (BugBunny queue name, HTTP base URL)
-3. Quick start — how another service calls this one
-4. Links to `docs/ai/contracts.md` for full contract reference
-
----
-
-## Step 6 — Show diff and wait for approval
-
-Show the complete diff of all generated/updated files.
-Wait for developer approval before proceeding to PR creation.
-The developer may adjust content before confirming.
-Do NOT create the PR until the docs are approved.

data/.claude/commands/test.md

@@ -1,28 +0,0 @@
-Run RSpec tests for BugBunny. Usage: /test [path]
-
-Ejecutá la suite de tests de BugBunny con Ruby 3.3.8.
-
-## Comando base
-
-```bash
-source /opt/homebrew/opt/chruby/share/chruby/chruby.sh && chruby ruby-3.3.8 && bundle exec rspec
-```
-
-Si se pasa un path como argumento, corré solo ese archivo o directorio:
-
-```bash
-source /opt/homebrew/opt/chruby/share/chruby/chruby.sh && chruby ruby-3.3.8 && bundle exec rspec $ARGUMENTS
-```
-
-## Después de correr los tests
-
-- Si hay failures: analizá el error, identificá la causa raíz, proponé el fix al usuario antes de tocar código
-- Si hay warnings de deprecación: reportalos al usuario
-- Si todos pasan: confirmá con el conteo de ejemplos y tiempo de ejecución
-
-## Convenciones de RSpec en este proyecto
-
-- Tests en `spec/`
-- Sin mocks de RabbitMQ real — usar doubles de Bunny
-- Describir comportamiento, no implementación
-- Un `context` por escenario, `it` con descripción en español o inglés consistente con el archivo

data/.claude/commands/yard.md

@@ -1,46 +0,0 @@
-Validate and generate YARD documentation for BugBunny. Usage: /yard
-
-Verificá y generá la documentación YARD de la gema.
-
-## Comandos
-
-Generar docs:
-```bash
-source /opt/homebrew/opt/chruby/share/chruby/chruby.sh && chruby ruby-3.3.8 && bundle exec yard doc
-```
-
-Ver métodos sin documentar:
-```bash
-source /opt/homebrew/opt/chruby/share/chruby/chruby.sh && chruby ruby-3.3.8 && bundle exec yard stats --list-undoc
-```
-
-## Estándar YARD de este proyecto
-
-Todo método público nuevo o modificado debe tener:
-
-```ruby
-# Descripción breve en una línea.
-#
-# Descripción extendida opcional si la firma no es autoexplicativa.
-#
-# @param nombre [Tipo] Descripción del parámetro
-# @return [Tipo] Descripción del valor de retorno
-# @raise [ClaseError] Condición bajo la cual se lanza
-# @example
-#   resultado = mi_metodo(arg)
-def mi_metodo(nombre)
-```
-
-## Tipos comunes en este proyecto
-
-- `[String]`, `[Integer]`, `[Boolean]`, `[Hash]`, `[Array]`, `[Symbol]`
-- `[Bunny::Session]`, `[Bunny::Channel]`, `[Bunny::MessageProperties]`
-- `[BugBunny::Session]`, `[BugBunny::Request]`, `[BugBunny::Configuration]`
-- `[Proc, nil]` para callbacks opcionales
-- `[void]` para métodos sin return value relevante
-
-## Después de correr
-
-- Reportá los métodos públicos sin documentar
-- No documentar métodos privados (YARD los ignora por defecto con `private`)
-- No documentar métodos triviales (`attr_reader`, `attr_accessor`) salvo que necesiten contexto

data/docs/_index.md

@@ -1,50 +0,0 @@
-# docs/_index.md — Documentation Manifest
-
-This file is the source of truth for the `docs/` directory structure.
-It is read by the `/release` command to know which files to generate or update.
-
----
-
-## Human documentation (developers integrating BugBunny)
-
-| File | Purpose |
-|---|---|
-| `concepts.md` | AMQP in 5 min, architecture diagram, RPC vs fire-and-forget, connection pool |
-| `howto/routing.md` | Routes DSL: `resources`, `namespace`, `member`, `collection`, `recognize` |
-| `howto/controller.md` | `params`, `before_action`, `after_action`, `around_action`, `rescue_from`, `render` |
-| `howto/resource.md` | CRUD methods, typed vs dynamic attributes, dirty tracking, validations, `.with` |
-| `howto/middleware_client.md` | Client-side middlewares: built-ins, custom, usage in Client and Resource |
-| `howto/middleware_consumer.md` | Consumer-side middlewares: execution order, writing, registering |
-| `howto/tracing.md` | Trace context propagation: `rpc_reply_headers`, `on_rpc_reply`, consumer middleware |
-| `howto/rails.md` | Full Rails setup: initializer, connection pool, Zeitwerk, Puma, Sidekiq, K8s health checks |
-| `howto/testing.md` | Bunny doubles, unit tests for controllers/middleware, integration helper |
-
-These files are referenced by `README.md`. Update them before updating the README.
-
----
-
-## AI documentation (agents consuming or maintaining BugBunny)
-
-Managed by `docs/ai/_index.md`. See that file for the full manifest and audience breakdown.
-
-| File | Audience | Purpose |
-|---|---|---|
-| `ai/_index.md` | internal + external | Manifest: version, profile, file index |
-| `ai/glossary.md` | internal + external | Domain terms with precise definitions |
-| `ai/architecture.md` | internal | Internal patterns, component map, data flows |
-| `ai/api.md` | external | Public API contracts |
-| `ai/faq_internal.md` | internal | Q&A for gem maintainers |
-| `ai/faq_external.md` | external | Q&A for gem integrators |
-| `ai/antipatterns.md` | internal + external | What NOT to do and why |
-| `ai/errors.md` | external | All exceptions with cause and resolution |
-
----
-
-## Update rules for `/release`
-
-1. Run tests first. If they fail, stop.
-2. Read this file to discover all files to update.
-3. For each file in **Human documentation**: update only sections affected by the changes in this release.
-4. For each file in **AI documentation**: update only sections affected by the changes. Update `version` in `ai/_index.md`.
-5. Update `README.md` last — it depends on `docs/howto/` being up to date.
-6. Show the full diff to the developer and wait for approval before touching version or CHANGELOG.

data/docs/ai/_index.md

@@ -1,56 +0,0 @@
----
-type: knowledge_base
-kind: gem
-name: bug_bunny
-version: 4.8.0
-profile: full
-language: ruby
-generated_by: gem-ai-setup@1.0.0
-audiences:
-  - internal
-  - external
-files:
-  - path: glossary.md
-    audience: [internal, external]
-  - path: architecture.md
-    audience: [internal]
-  - path: api.md
-    audience: [external]
-  - path: faq_internal.md
-    audience: [internal]
-  - path: faq_external.md
-    audience: [external]
-  - path: antipatterns.md
-    audience: [internal, external]
-  - path: errors.md
-    audience: [external]
----
-
-## What is BugBunny?
-
-BugBunny is a Ruby gem that implements a RESTful routing layer over AMQP (RabbitMQ). It lets microservices communicate via RabbitMQ using familiar HTTP patterns: verbs (GET, POST, PUT, DELETE), controllers, declarative routes, synchronous RPC, and fire-and-forget.
-
-**Problem solved:** Eliminates direct HTTP coupling between microservices. RabbitMQ acts as the message bus with the same ergonomics as a web framework.
-
-## Version
-
-4.8.0 — April 2026
-
-## Key features in this version
-
-- Namespace routing (`namespace :admin { resources :users }`)
-- `after_action` filter (runs after action, not after `before_action` halts)
-- `render(headers:)` — inject custom headers into RPC replies
-- `Consumer#shutdown` — explicit graceful shutdown with health check cleanup
-- `Configuration#validate!` — invoked automatically at end of `BugBunny.configure`
-- Producer/Session caching per connection slot (prevents double-consumer AMQP error)
-- Expanded `SENSITIVE_KEYS` filter in `safe_log`
-- `ConsumerMiddleware::Stack` mutex for thread-safe registration
-
-## How to use this knowledge base
-
-- **Building an integration** → start with `api.md`, then `faq_external.md`
-- **Debugging errors** → `errors.md`
-- **Avoiding mistakes** → `antipatterns.md`
-- **Understanding internals** → `architecture.md`, then `faq_internal.md`
-- **Domain vocabulary** → `glossary.md`

data/docs/ai/antipatterns.md

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