Skip to main content
Open source ยท Apache 2.0

oncebox

Transactional Outbox and Inbox for Spring Boot

OrderService.java
@Transactional
@OutboxPublish(eventType = "order-created")
public OrderDto create(OrderCreateDto dto) {
Order order = repository.save(mapper.toEntity(dto));
return mapper.toDto(order);
}

From your transaction to your listener

  1. 1

    Write

    Your transaction stores the business change and the event in the outbox table. Both commit, or neither does.

  2. 2

    Poll

    A poller per event type picks up a batch of due events and locks it, so two instances never take the same events.

  3. 3

    Send

    The batch goes to Kafka or RabbitMQ and counts as sent once the broker confirms it. Failures are retried; events that run out of retries move to a dead letter queue.

  4. 4

    Deliver

    The broker delivers the message at least once, and the event id travels with it.

  5. 5

    Consume once

    The inbox remembers the id together with your operation. When the same event arrives again, it is skipped.

What's in the box

Atomic with your data

Events are written in the same database transaction as the business change. Both commit, or neither does.

Your database

PostgreSQL 16+, MySQL 8.0.13+ and Oracle 23+, each with a dialect module of its own. The tables come as versioned migrations, applied with Flyway or Liquibase or left to your own.

Messaging integration

Apache Kafka 3.7+ and RabbitMQ 3.12+ on both sides: the outbox sends through your template, the inbox deduplicates in your listener.

At-least-once processing

An event is marked processed only after Kafka acks or RabbitMQ confirms it, and failures are retried with per-type backoff, so your listener gets every event at least once.

Effectively-once processing

The inbox records event ids in the transaction of your handler, so a redelivered event never changes data twice.

At-most-once processing

The non-transactional consumer commits the event id before your operation runs, so a side effect such as an email is never repeated.

Dead letter queue

Events that exhaust their retries move to a DLQ table atomically and are reviewed and retried through a REST API.

Safe under failure

Stuck batches are recovered, a late finalization is fenced off by a lock token, and every timestamp comes from the database clock.

Observable

Micrometer gauges, counters and timers for events, background jobs and the inbox cache, with ready Grafana dashboards.