Package com.babelqueue.outbox

package com.babelqueue.outbox
Optional transactional-outbox helper (ADR-0029): the producer-side mirror of the consumer-side idempotency helper (ADR-0022).

It removes the producer dual write — "commit the business row" and "publish to the broker" are two systems that can disagree on a crash. The Outbox writer persists the EnvelopeCodec-encoded envelope into the caller's own database, inside the caller's own transaction, so it commits or rolls back atomically with the business data; the OutboxRelay then publishes the durable rows through the OutboxTransport seam afterwards. Exactly-once handoff into the broker, then at-least-once on the wire as always.

The pieces:

  • OutboxStore — the persistence contract the caller binds to their DB (the core adds no DB driver, GR-7); InMemoryOutboxStore is the reference for tests/demos.
  • Outbox — write(envelope): encode via the frozen codec (bytes unchanged, GR-1) and save. The transaction boundary is the caller's; this never begins/commits.
  • OutboxRelay — flush()/drain(maxPasses): publish the stored bytes verbatim, mark published only after the transport accepts, markFailed + bounded linear backoff on a throw (row stays pending, batch continues).

The wire envelope is unchanged (schema_version: 1) — the outbox stores it byte-for-byte and never adds an envelope field. See .ssot/architecture/adr/0029-transactional-outbox-helper.md.

  • Class
    Description
    InMemoryOutboxStore
    Process-local reference OutboxStore backed by a map — for tests and single-process demos.
    Outbox
    The write side of the transactional outbox (ADR-0029): turn a BabelQueue Envelope into a stored outbox row, so the message is persisted atomically with the business data and a separate OutboxRelay publishes it later.
    OutboxRecord
    One pending row read back from an OutboxStore for the OutboxRelay to publish.
    OutboxRelay
    The read/publish side of the transactional outbox (ADR-0029): drain pending rows the Outbox writer committed and forward each onto the broker through the OutboxTransport seam, marking every row published or failed.
    OutboxRelay.Sleeper
    Sleeps for a number of milliseconds between a failed publish and the next attempt.
    OutboxRelayResult
    Summary of an OutboxRelay run: how many pending rows were published and how many failed (and were left pending for a later retry).
    OutboxStore
    The persistence seam for the transactional outbox (ADR-0029) — the durable "outbox" table that an Outbox writer fills and an OutboxRelay drains.
    OutboxTransport
    The minimal publish-only broker seam the OutboxRelay forwards through — publish one already-encoded envelope onto a queue.