Spring Boot receipt delivery project: add a recoverable worker contract

Build from checked pieces

The existing receipt delivery project is a plan, not a deployed service. The kit separately checks an atomic receipt/outbox insert, a token and expiry predicate, and a destination event-ID ledger. A practical next implementation would place the receipt API and outbox write in one service transaction, then run a relay that claims a bounded batch, sends stable event IDs, and acknowledges only with its current claim token.

The destination inserts the event ID and applies its business change in one transaction. If it sees the same ID again, it must classify the replay and avoid a second change. The local duplicate test currently throws; an API or broker adapter still needs to turn that into a safe acknowledgement. For a changed payload under the same ID, reject and investigate rather than pretending the new event was processed.

Prove recovery before exposure

Keep worker concurrency, batch size, lease duration and retry cap configurable and measured. Test process termination after each handoff against the chosen database and broker. The target connection pool must cover request and worker load; the ready probe should reflect dependencies the service cannot operate without. None of those deployment properties is established by the local kit. The test matrix names the missing failure points.

Checked source

// One public receipt request produces one durable event ID.
receiptTransaction.executeWithoutResult(status -> {
    receiptRepository.insert(receiptId, tenantId, "accepted");
    outboxRepository.insert(eventId, receiptId, "pending");
});
// A separate relay claims, sends, and acknowledges with its current token.

Verification boundary

OutboxWriteContractTest.receiptAndOutboxRowCommitOrRollBackTogether, OutboxLeaseContractTest.expiredLeaseCanBeReclaimedButOldWorkerCannotAcknowledge and ConsumerDedupContractTest.repeatedEventIdCannotApplyTheStockMutationTwice runs in the downloadable Spring source kit. The excerpt is shortened; the kit contains the complete tests.

Costs and limits

This is an implementation plan grounded in separate checked fixtures, not a runnable combined application. A real service adds migrations, broker I/O, pool sizing, observability, tenant authorization and operations under load. The current API uses an in-memory store.

Common Mistakes

• Do not label the project deployed because its component tests pass.
• Do not return durable acceptance before the command transaction commits.
• Do not turn a duplicate event into a second business mutation.

Read next

Spring receipt delivery project: atomic write, guarded claim and replay, Spring transactional outbox: commit a receipt and event row together, Spring outbox claims: allow recovery after a worker lease expires, Spring consumer deduplication: commit the event ID with the mutation.