ring:using-outbox

ring:using-outbox

When to use

Sweep mode:

• "Sweep for transactional outbox violations"
• "Find send-and-pray emits"
• "Are we wrapping DB transactions with WithOutboxTx?"
• "Migrate this service from DIY outbox to lib-streaming + lib-commons/outbox"
• "Audit relay loops for hand-rolled poller patterns"

Reference mode:

• "How does the transactional outbox pattern work?"
• "Which writer interface do I implement for X?"
• "What goes in OutboxEnvelope?"
• "How do I wire the relay loop?"
• "How does WithOutboxTx interact with MongoDB sessions?"

Skip when

• Working on non-Go services
• Service has no events to emit (pure read-side, BFF)
• Working on frontend code

Related

Parent surface: ring:using-lib-streaming (full streaming bus) Repository side: ring:using-lib-commons (lib-commons/outbox dispatcher, repository, handler registry) Adjacent: ring:instrumenting-streaming-events (eventable-point identification → emit wiring), ring:using-runtime (panic-safe relay loops), ring:using-assert (invariant checks on envelope decode)

---

The Pattern

The transactional outbox solves one operational invariant: business state and the event that announces it must commit atomically, or not at all. Without it, three failure modes are inevitable in production:

1. Lost event. Business state commits, the producer calls broker.Emit, the broker is down or the network blips — the event vanishes. The ledger now believes a transaction happened that no downstream consumer ever heard about.
2. Phantom event. Producer emits successfully, then the DB commit fails. Downstream consumers now act on a transaction that never happened.
3. Send-and-pray. Code paths that emit on a best-effort basis "and we'll log it if it fails" — a polite name for systematic data loss under sustained broker outages.

The outbox pattern fixes this by writing the event to an outbox table inside the same database transaction as the business state. Commit is atomic: either both rows persist or neither does. A separate process — the relay (also called dispatcher or poller) — reads pending outbox rows and publishes them to the broker, marking each row PUBLISHED on success. Delivery becomes at-least-once: if the relay crashes between publish and mark, the row stays pending and the next cycle retries. Consumers must be idempotent — that is the cost of at-least-once.