docs(wiki): sync retry/dlq topology and runtime template state updates

2026-04-06 18:42:18 -07:00
parent 0a6fae0dca
commit 99d2b06419
2 changed files with 46 additions and 0 deletions

@@ -138,6 +138,28 @@ All BEDS queues are:
This is non-negotiable for a production framework. The performance cost of persistence (disk write per message) is acceptable given the correctness guarantee. This is non-negotiable for a production framework. The performance cost of persistence (disk write per message) is acceptable given the correctness guarantee.
## DLQ and Retry Topology (Implemented)
For the active POC queues (`rec.read`, `rec.write`), BEDS now provisions:
- Primary queue: `{tag}rec.read` / `{tag}rec.write`
- Retry queue: `{tag}rec.read.retry` / `{tag}rec.write.retry`
- Dead-letter queue: `{tag}rec.read.dlq` / `{tag}rec.write.dlq`
Dead-letter flow:
- Primary queues are configured with dead-letter exchange `beds.dlx`.
- Non-retryable failures (`nack requeue=false`) route to `*.dlq` via routing keys
`rec.read.dlq` and `rec.write.dlq`.
Retry flow:
- Retryable failures are republished to `*.retry` queues.
- Retry queues apply TTL backoff and dead-letter back to `beds.events` using the
original routing keys (`rec.read` / `rec.write`).
This avoids tight immediate requeue loops and creates deterministic failure lanes.
## The `vhost` Isolation Model ## The `vhost` Isolation Model
Each environment gets its own RabbitMQ virtual host. A vhost is a completely isolated namespace — queues, exchanges, and bindings in one vhost are invisible to another. A RabbitMQ user is granted access to specific vhosts. Each environment gets its own RabbitMQ virtual host. A vhost is a completely isolated namespace — queues, exchanges, and bindings in one vhost are invisible to another. A RabbitMQ user is granted access to specific vhosts.
@@ -151,3 +173,21 @@ vhost: dev ← development traffic
Even if all three environments share one RabbitMQ instance, they are fully isolated. A message published to `prod` cannot be consumed by a `dev` consumer. Even if all three environments share one RabbitMQ instance, they are fully isolated. A message published to `prod` cannot be consumed by a `dev` consumer.
This was the operational pattern in the Namaste homelab — one RabbitMQ instance, three vhosts, multiple concurrent dev sessions running without interfering with each other. This was the operational pattern in the Namaste homelab — one RabbitMQ instance, three vhosts, multiple concurrent dev sessions running without interfering with each other.
## POC Verification
Current proof-of-concept verification for the two active appServer brokers is covered by integration tests:
- `tests/broker_pool_test.rs` validates that configured rBroker/wBroker pool instances spawn.
- `tests/broker_message_flow_test.rs` validates end-to-end message flow by publishing `ping` events to
`rec.read` and `rec.write` and asserting broker replies.
- `tests/broker_message_flow_test.rs` also validates logger sequence round-trip by publishing a `write`
event to `rec.write` with `template="Logger"`, then fetching via `fetch` on `rec.read` and asserting
that the newly written log message is returned.
Current logger sequence in POC now writes and reads through MongoDB (`msLogs`) via the
`Logger` template path (`rec.write` for write, `rec.read` for fetch), using credentials from
the active environment config.
These tests provide a lightweight deployment confidence check while the framework is still in the
"POC before guardrails" phase.

@@ -48,6 +48,12 @@ Immediate objective:
Guardrails are intentionally deferred until POC behavior is stable. Guardrails are intentionally deferred until POC behavior is stable.
Implementation status update:
- Phase A transport stability evidence exists: live RabbitMQ round-trip tests for `rec.read` and `rec.write` ping paths.
- Phase B has started: REC template registry loading and startup validation are now implemented in IPL.
- Phase B progression: runtime template registry state is now persisted and passed into broker workers for dispatch-time template validation.
- Reliability progression: deterministic ack/nack behavior and retry/DLQ queue topology are implemented for `rec.read` and `rec.write`.
## Must-Keep Invariants ## Must-Keep Invariants
1. AMQP-first data path for application operations. 1. AMQP-first data path for application operations.