From 99d2b06419ccd3b1433b67667a544d5c5b38fd0b Mon Sep 17 00:00:00 2001 From: gramps Date: Mon, 6 Apr 2026 18:42:18 -0700 Subject: [PATCH] docs(wiki): sync retry/dlq topology and runtime template state updates --- 06-queue-topology.md | 40 +++++++++++++++++++++++++++++++++++++ 10-modernization-roadmap.md | 6 ++++++ 2 files changed, 46 insertions(+) diff --git a/06-queue-topology.md b/06-queue-topology.md index 489ea82..f5559b9 100644 --- a/06-queue-topology.md +++ b/06-queue-topology.md @@ -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. +## 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 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. 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. diff --git a/10-modernization-roadmap.md b/10-modernization-roadmap.md index 335cff0..cc5f160 100644 --- a/10-modernization-roadmap.md +++ b/10-modernization-roadmap.md @@ -48,6 +48,12 @@ Immediate objective: 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 1. AMQP-first data path for application operations.