review-followup Wave 3 라운드 2(P18): outbox canonical 통일, composition 모듈, legacy Kafka seam 삭제

- 결정 7: `LegacyOutboxAppendPort`·legacy 저장 모델·relay·Kafka R0 seam 삭제, 템플릿 JSON encoder(`JsonIntegrationEventEncoder`),
  durable operation·sample 이벤트가 `OutboxAppendPort` + encoder로, persistence-jpa V19(pre-canonical 미발행 row 거부)
- 결정 3: outbox relay·멱등성 executor 조립을 `composition:outbox-relay`·`composition:idempotency`로,
  sample이 복사한 bootstrap 인프라를 `composition:service-runtime`으로(sample `SampleIdempotencyConfig` 복사본 삭제)
- persistence-jpa outbox·멱등성 패키지 feature 기준 이동, messaging outbox·inbox leaf를 reliability / reliability-jdbc-postgresql로
- messaging outbox header를 jsonb로(P18-new-1 — `\`로 끝나는 값이 다음 header를 삼키던 결함)
- 통합(충돌 22건): P25 A-10c(전략 선택 설정 삭제)를 service-runtime `DomainContextConfig`에 적용, P25 startup 예외 통합을
  composition 설정 테스트에, P25 `CommandUseCase.handle` 이름을 PG 통합 테스트에, P15 `EventJson`은 호출자 0이 되어 삭제
- root CLAUDE.md의 legacy seam 문장 수정(P18-new-2)

검증: ./gradlew check architectureCheck verifyDependencyLocks verifyPublicPathSnapshot :app-bootstrap:verifyEnvKeys
configContractCheck :app-bootstrap:integrationTest :sample-portfolio:integrationTest :sample-portfolio:systemTest
persistence-jpa jpaPlatformContractTest·postgresql{Idempotency,OutboxAppendTransactional,OutboxConcurrentRelay,OutboxRowLifecycle}IntegrationTest
:messaging:messaging-reliability-jdbc-postgresql:integrationTest --continue 통과(700 task)

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
donghyeon-ka
2026-09-29 12:30:01 +09:00
co-authored by Claude Opus 5.5
parent b5e3c03777
commit 6397f52dc8
45 changed files with 298 additions and 532 deletions
@@ -0,0 +1,206 @@
package dev.caskeleton.messaging.inbox;
import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.messaging.api.MessageId;
import dev.caskeleton.messaging.testkit.DockerAvailability;
import java.io.IOException;
import java.io.InputStream;
import java.nio.charset.StandardCharsets;
import java.sql.Connection;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;
import java.time.Instant;
import java.util.concurrent.atomic.AtomicInteger;
import javax.sql.DataSource;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.condition.EnabledIf;
import org.postgresql.ds.PGSimpleDataSource;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;
import org.testcontainers.postgresql.PostgreSQLContainer;
/**
* Certifies the inbox against a real PostgreSQL.
*
* <p>The whole pattern rests on a uniqueness constraint and a shared transaction. Both are database
* behaviours: a double can be written to agree with them, and a real one either enforces them or
* does not.
*
* <p>The last test is the one that matters most. It commits an inbox reservation and a business
* write together, then rolls a second attempt back, and asserts that the side effect did not happen
* twice and the reservation did not survive the rollback.
*/
@Testcontainers
@EnabledIf("dockerAvailable")
class InboxPostgresIT {
private static final Instant NOW = Instant.parse("2026-08-10T09:15:00Z");
// Scope-based leak analysis cannot see the owner: @Container: the Testcontainers JUnit extension
// owns this lifecycle.
@SuppressWarnings("resource")
@Container
private static final PostgreSQLContainer POSTGRES =
new PostgreSQLContainer("postgres:16-alpine")
.withDatabaseName("messaging")
.withUsername("messaging")
.withPassword("messaging");
private DataSource dataSource;
private org.springframework.transaction.support.TransactionTemplate transactions;
private JdbcInboxRepository repository;
static boolean dockerAvailable() {
return DockerAvailability.isAvailable();
}
@BeforeEach
void migrate() throws SQLException, IOException {
dataSource = dataSource();
try (Connection connection = dataSource.getConnection();
Statement statement = connection.createStatement()) {
statement.execute("DROP TABLE IF EXISTS messaging_inbox");
statement.execute("DROP TABLE IF EXISTS projections");
statement.execute(migration());
statement.execute("CREATE TABLE projections (id TEXT PRIMARY KEY, applied INT NOT NULL)");
}
repository = new JdbcInboxRepository(dataSource);
// A real Spring transaction, because the port's contract is about joining one. The previous
// tests called the Connection overload directly, which proved that overload works and said
// nothing about the interface method every consumer actually calls.
transactions =
new org.springframework.transaction.support.TransactionTemplate(
new org.springframework.jdbc.datasource.DataSourceTransactionManager(dataSource));
}
@Test
void theFirstReservationSucceedsAndTheSecondDoesNot() {
MessageId messageId = MessageId.newId();
assertThat(inTransaction(() -> repository.reserve(messageId, "order-projection", NOW)))
.isTrue();
assertThat(inTransaction(() -> repository.reserve(messageId, "order-projection", NOW)))
.isFalse();
}
@Test
void twoConsumersEachReserveTheSameMessageOnce() {
MessageId messageId = MessageId.newId();
assertThat(inTransaction(() -> repository.reserve(messageId, "order-projection", NOW)))
.isTrue();
assertThat(inTransaction(() -> repository.reserve(messageId, "billing-projection", NOW)))
.isTrue();
assertThat(inTransaction(() -> repository.reserve(messageId, "order-projection", NOW)))
.isFalse();
}
@Test
void aProcessedMessageIsVisibleToTheQuery() {
MessageId messageId = MessageId.newId();
inTransaction(() -> repository.reserve(messageId, "order-projection", NOW));
assertThat(repository.isProcessed(messageId, "order-projection")).isTrue();
assertThat(repository.isProcessed(messageId, "billing-projection")).isFalse();
}
@Test
void aRedeliveryDoesNotApplyTheSideEffectTwice() throws SQLException {
MessageId messageId = MessageId.newId();
AtomicInteger applied = new AtomicInteger();
handle(messageId, applied);
handle(messageId, applied);
assertThat(applied.get()).as("the handler ran once").isEqualTo(1);
assertThat(projectionCount("o-1")).isEqualTo(1);
}
@Test
void aRolledBackTransactionLeavesNoReservationAndNoSideEffect() throws SQLException {
MessageId messageId = MessageId.newId();
// Through the interface method and a real Spring transaction. This is the path a consumer
// takes; the old version called the Connection overload, which is the one path that was never
// in doubt.
try {
transactions.executeWithoutResult(
status -> {
assertThat(repository.reserve(messageId, "order-projection", NOW)).isTrue();
new org.springframework.jdbc.core.JdbcTemplate(dataSource)
.execute("INSERT INTO projections (id, applied) VALUES ('o-2', 1)");
status.setRollbackOnly();
});
} catch (RuntimeException rolledBack) {
// setRollbackOnly is the mechanism; an UnexpectedRollbackException is not a failure here.
}
assertThat(repository.isProcessed(messageId, "order-projection"))
.as("the reservation must not outlive the transaction that made it")
.isFalse();
assertThat(projectionCount("o-2")).isZero();
}
@Test
void retentionRemovesOldRows() {
MessageId purged = MessageId.newId();
inTransaction(() -> repository.reserve(purged, "order-projection", NOW));
assertThat(repository.purgeProcessedBefore(NOW.plusSeconds(1), 100)).isEqualTo(1);
}
/** Reserves and writes inside one Spring transaction, exactly as an idempotent consumer must. */
private void handle(MessageId messageId, AtomicInteger applied) {
transactions.executeWithoutResult(
status -> {
if (!repository.reserve(messageId, "order-projection", NOW)) {
status.setRollbackOnly();
return;
}
new org.springframework.jdbc.core.JdbcTemplate(dataSource)
.execute("INSERT INTO projections (id, applied) VALUES ('o-1', 1)");
applied.incrementAndGet();
});
}
private <T> T inTransaction(java.util.function.Supplier<T> work) {
return transactions.execute(status -> work.get());
}
private int projectionCount(String id) throws SQLException {
try (Connection connection = dataSource.getConnection();
PreparedStatement statement =
connection.prepareStatement("SELECT count(*) FROM projections WHERE id = ?")) {
statement.setString(1, id);
try (ResultSet results = statement.executeQuery()) {
results.next();
return results.getInt(1);
}
}
}
private static DataSource dataSource() {
PGSimpleDataSource source = new PGSimpleDataSource();
source.setUrl(POSTGRES.getJdbcUrl());
source.setUser(POSTGRES.getUsername());
source.setPassword(POSTGRES.getPassword());
return source;
}
private static String migration() throws IOException {
try (InputStream stream =
InboxPostgresIT.class
.getClassLoader()
.getResourceAsStream("db/migration/messaging/V1101__messaging_inbox.sql")) {
if (stream == null) {
throw new IOException("the inbox migration is missing from the classpath");
}
return new String(stream.readAllBytes(), StandardCharsets.UTF_8);
}
}
}
@@ -0,0 +1,209 @@
package dev.caskeleton.messaging.outbox;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatCode;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.messaging.admin.AdminOperationLease;
import dev.caskeleton.messaging.admin.AdminOperationState;
import dev.caskeleton.messaging.admin.PlanDigest;
import dev.caskeleton.messaging.api.error.MessageAuthorizationException;
import dev.caskeleton.messaging.testkit.DockerAvailability;
import java.io.IOException;
import java.io.InputStream;
import java.nio.charset.StandardCharsets;
import java.sql.Connection;
import java.sql.SQLException;
import java.sql.Statement;
import java.time.Duration;
import java.time.Instant;
import javax.sql.DataSource;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.condition.EnabledIf;
import org.postgresql.ds.PGSimpleDataSource;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;
import org.testcontainers.postgresql.PostgreSQLContainer;
/**
* Certifies the durable journal against a real PostgreSQL.
*
* <p>The properties that matter here belong to the database, not to Java. "Exactly one replica
* executes an approval" is a primary-key conflict; "a stalled runtime cannot overwrite its
* successor" is a conditional update on a fencing token. An in-memory double can be written to
* agree with both without either being true of the deployed schema, which is exactly how the map
* this replaced looked correct for as long as nobody restarted a replica.
*/
@Testcontainers
@EnabledIf("dockerAvailable")
class AdminOperationJournalPostgresIT {
private static final Instant NOW = Instant.parse("2026-08-10T09:15:00Z");
private static final Duration LEASE = Duration.ofMinutes(5);
private static final String TICKET = "CHG-1042";
private static final PlanDigest DIGEST = PlanDigest.ofCanonical("REDRIVE|orders.v1.dlq|50");
// Scope-based leak analysis cannot see the owner: @Container: the Testcontainers JUnit extension
// owns this lifecycle.
@SuppressWarnings("resource")
@Container
private static final PostgreSQLContainer POSTGRES =
new PostgreSQLContainer("postgres:16-alpine")
.withDatabaseName("messaging")
.withUsername("messaging")
.withPassword("messaging");
private JdbcAdminOperationJournal journal;
static boolean dockerAvailable() {
return DockerAvailability.isAvailable();
}
@BeforeEach
void migrate() throws SQLException, IOException {
DataSource dataSource = dataSource();
try (Connection connection = dataSource.getConnection();
Statement statement = connection.createStatement()) {
statement.execute("DROP TABLE IF EXISTS messaging_admin_operation");
statement.execute(migration("V1003__messaging_admin_operation_journal.sql"));
}
journal = new JdbcAdminOperationJournal(dataSource);
}
@Test
@DisplayName("the primary key, not application code, decides which replica wins")
void thePrimaryKeyDecidesWhichReplicaWins() {
journal.begin(TICKET, DIGEST, "op-1", "replica-a", LEASE, NOW);
assertThatThrownBy(
() -> journal.begin(TICKET, DIGEST, "op-2", "replica-b", LEASE, NOW.plusSeconds(1)))
.isInstanceOf(MessageAuthorizationException.class)
.hasMessageContaining("replica-a");
}
@Test
@DisplayName("a completed operation survives the restart that forgot the map")
void aCompletedOperationSurvivesARestart() {
AdminOperationLease lease = journal.begin(TICKET, DIGEST, "op-1", "replica-a", LEASE, NOW);
journal.complete(lease, 50, NOW.plusSeconds(30));
// A fresh journal object over the same database is what a restarted replica sees.
JdbcAdminOperationJournal afterRestart = new JdbcAdminOperationJournal(dataSource());
assertThatThrownBy(
() ->
afterRestart.begin(TICKET, DIGEST, "op-3", "replica-a", LEASE, NOW.plusSeconds(60)))
.isInstanceOf(MessageAuthorizationException.class)
.hasMessageContaining("already executed");
}
@Test
@DisplayName("an expired lease is taken over at its checkpoint, under a higher token")
void anExpiredLeaseIsTakenOverAtItsCheckpoint() {
AdminOperationLease first = journal.begin(TICKET, DIGEST, "op-1", "replica-a", LEASE, NOW);
journal.checkpoint(first, 30, LEASE, NOW.plusSeconds(10));
AdminOperationLease resumed =
journal.begin(TICKET, DIGEST, "op-1", "replica-b", LEASE, NOW.plus(Duration.ofMinutes(10)));
assertThat(resumed.resumeFrom()).isEqualTo(30);
assertThat(resumed.leaseToken()).isEqualTo(first.leaseToken() + 1);
}
@Test
@DisplayName("a live lease is not taken over")
void aLiveLeaseIsNotTakenOver() {
journal.begin(TICKET, DIGEST, "op-1", "replica-a", LEASE, NOW);
assertThatThrownBy(
() ->
journal.begin(
TICKET, DIGEST, "op-1", "replica-b", LEASE, NOW.plus(Duration.ofMinutes(1))))
.isInstanceOf(MessageAuthorizationException.class)
.hasMessageContaining("is being executed by");
}
@Test
@DisplayName("a superseded runtime cannot write over the one that took over")
void aSupersededRuntimeCannotWriteOverItsSuccessor() {
AdminOperationLease stale = journal.begin(TICKET, DIGEST, "op-1", "replica-a", LEASE, NOW);
journal.checkpoint(stale, 30, LEASE, NOW.plusSeconds(10));
AdminOperationLease successor =
journal.begin(TICKET, DIGEST, "op-1", "replica-b", LEASE, NOW.plus(Duration.ofMinutes(10)));
journal.checkpoint(successor, 45, LEASE, NOW.plus(Duration.ofMinutes(11)));
assertThatThrownBy(() -> journal.complete(stale, 30, NOW.plus(Duration.ofMinutes(12))))
.isInstanceOf(MessageAuthorizationException.class)
.hasMessageContaining("no longer holds the lease");
assertThat(journal.find(TICKET, DIGEST))
.hasValueSatisfying(
record -> {
assertThat(record.itemsCompleted()).isEqualTo(45);
assertThat(record.state()).isEqualTo(AdminOperationState.STARTED);
});
}
@Test
@DisplayName("a failed operation is resumable immediately and records why it stopped")
void aFailedOperationIsResumableImmediately() {
AdminOperationLease first = journal.begin(TICKET, DIGEST, "op-1", "replica-a", LEASE, NOW);
journal.fail(first, 12, "MESSAGE_BROKER_UNAVAILABLE", NOW.plusSeconds(6));
assertThat(journal.find(TICKET, DIGEST))
.hasValueSatisfying(
record -> {
assertThat(record.state()).isEqualTo(AdminOperationState.FAILED);
assertThat(record.failureCode()).contains("MESSAGE_BROKER_UNAVAILABLE");
});
assertThatCode(
() -> {
AdminOperationLease resumed =
journal.begin(TICKET, DIGEST, "op-1", "replica-a", LEASE, NOW.plusSeconds(7));
assertThat(resumed.resumeFrom()).isEqualTo(12);
})
.doesNotThrowAnyException();
}
@Test
@DisplayName("the schema refuses a digest that is not a SHA-256")
void theSchemaRefusesADigestThatIsNotASha256() throws SQLException {
try (Connection connection = dataSource().getConnection();
Statement statement = connection.createStatement()) {
assertThatThrownBy(
() ->
statement.execute(
"""
INSERT INTO messaging_admin_operation (
approval_ticket, plan_digest, operation_id, state,
lease_owner, lease_expires_at, started_at)
VALUES ('CHG-9', 'not-a-digest', 'op', 'STARTED', 'r', now(), now())
"""))
.as("a malformed digest in the journal makes the uniqueness key meaningless")
.isInstanceOf(SQLException.class);
}
}
private static DataSource dataSource() {
PGSimpleDataSource source = new PGSimpleDataSource();
source.setUrl(POSTGRES.getJdbcUrl());
source.setUser(POSTGRES.getUsername());
source.setPassword(POSTGRES.getPassword());
return source;
}
private static String migration(String fileName) throws IOException {
try (InputStream stream =
AdminOperationJournalPostgresIT.class
.getClassLoader()
.getResourceAsStream("db/migration/messaging/" + fileName)) {
if (stream == null) {
throw new IOException("migration " + fileName + " is missing from the classpath");
}
return new String(stream.readAllBytes(), StandardCharsets.UTF_8);
}
}
}
@@ -0,0 +1,642 @@
package dev.caskeleton.messaging.outbox;
import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.messaging.api.ContentType;
import dev.caskeleton.messaging.api.MessageId;
import dev.caskeleton.messaging.api.MessageType;
import dev.caskeleton.messaging.api.SchemaVersion;
import dev.caskeleton.messaging.api.destination.DestinationName;
import dev.caskeleton.messaging.reliability.OutboxCanonicalMetadata;
import dev.caskeleton.messaging.reliability.OutboxLease;
import dev.caskeleton.messaging.reliability.OutboxRecord;
import dev.caskeleton.messaging.reliability.OutboxStatus;
import dev.caskeleton.messaging.testkit.DockerAvailability;
import java.io.IOException;
import java.io.InputStream;
import java.nio.charset.StandardCharsets;
import java.sql.Connection;
import java.sql.SQLException;
import java.sql.Statement;
import java.time.Duration;
import java.time.Instant;
import java.util.List;
import java.util.Map;
import java.util.Optional;
import javax.sql.DataSource;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.condition.EnabledIf;
import org.postgresql.ds.PGSimpleDataSource;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;
import org.testcontainers.postgresql.PostgreSQLContainer;
/**
* Certifies the outbox against a real PostgreSQL.
*
* <p>The pattern's guarantees are claims about a database, not about Java: that a row and a
* business change commit together, that two relay instances cannot claim the same row, and that an
* ambiguous publish leaves the row claimable under its original identity. An in-memory double can
* be written to agree with any of those; only a real database settles them.
*/
@Testcontainers
@EnabledIf("dockerAvailable")
class OutboxPostgresIT {
private static final Instant NOW = Instant.parse("2026-08-10T09:15:00Z");
// Scope-based leak analysis cannot see the owner: @Container: the Testcontainers JUnit extension
// owns this lifecycle.
@SuppressWarnings("resource")
@Container
private static final PostgreSQLContainer POSTGRES =
new PostgreSQLContainer("postgres:16-alpine")
.withDatabaseName("messaging")
.withUsername("messaging")
.withPassword("messaging");
private DataSource dataSource;
private org.springframework.transaction.support.TransactionTemplate transactions;
private JdbcOutboxRepository repository;
static boolean dockerAvailable() {
return DockerAvailability.isAvailable();
}
@BeforeEach
void migrate() throws SQLException, IOException {
dataSource = dataSource();
try (Connection connection = dataSource.getConnection();
Statement statement = connection.createStatement()) {
statement.execute("DROP TABLE IF EXISTS messaging_outbox");
// The inbox migration ships in the same module now, so "every migration" creates its table
// too.
statement.execute("DROP TABLE IF EXISTS messaging_inbox");
// Every migration in order, not just V1: a test that applies part of the schema certifies a
// database nobody deploys.
for (String migration : migrations()) {
statement.execute(migration);
}
}
repository = new JdbcOutboxRepository(dataSource);
// A real Spring transaction: the port's contract is that append joins the caller's, and the
// previous tests proved only that the Connection overload worked.
transactions =
new org.springframework.transaction.support.TransactionTemplate(
new org.springframework.jdbc.datasource.DataSourceTransactionManager(dataSource));
}
@Test
void anAppendedRowIsClaimableAndRoundTripsIntact() {
OutboxRecord record = record();
appendInTransaction(record);
List<OutboxRecord> leased = claim("relay-a", NOW).stream().map(OutboxLease::record).toList();
assertThat(leased)
.singleElement()
.satisfies(
leasedRecord -> {
assertThat(leasedRecord.messageId()).isEqualTo(record.messageId());
assertThat(leasedRecord.messageType()).isEqualTo(record.messageType());
assertThat(leasedRecord.payload()).isEqualTo(record.payload());
assertThat(leasedRecord.metadata().partitionKey())
.as("the routing key is a column the relay can read without decoding the payload")
.contains("acct-1");
});
}
@Test
void aLeasedRowIsInvisibleToASecondRelayInstance() {
appendInTransaction(record());
List<OutboxLease> first = claim("relay-a", NOW);
List<OutboxLease> second = claim("relay-b", NOW);
assertThat(first).hasSize(1);
assertThat(second).as("SKIP LOCKED plus the lease keeps two relays off the same row").isEmpty();
}
@Test
void anExpiredLeaseBecomesClaimableAgain() {
appendInTransaction(record());
claim("relay-a", NOW);
List<OutboxLease> reclaimed = claim("relay-b", NOW.plusSeconds(31));
assertThat(reclaimed).hasSize(1);
}
@Test
void anAmbiguousRowStaysClaimableUnderItsOriginalIdentity() {
OutboxRecord record = record();
appendInTransaction(record);
// A terminal write is checked against the lease token, so `markAmbiguous` takes the lease that
// owns the row; no identity-keyed write exists for one relay to put an outcome on a row another
// relay currently owns.
OutboxLease lease = claim("ambiguous-relay", NOW).getFirst();
repository.markAmbiguous(lease, "CONFIRM_TIMEOUT", NOW, NOW);
assertThat(repository.find(record.messageId()).orElseThrow().status())
.isEqualTo(OutboxStatus.AMBIGUOUS);
assertThat(claim("relay-b", NOW))
.singleElement()
.satisfies(retry -> assertThat(retry.messageId()).isEqualTo(record.messageId()));
}
@Test
void aPublishedRowIsNotClaimedAgain() {
OutboxRecord record = record();
appendInTransaction(record);
OutboxLease lease = claim("relay-a", NOW).getFirst();
repository.markPublished(lease, NOW);
assertThat(repository.find(record.messageId()).orElseThrow().status())
.isEqualTo(OutboxStatus.PUBLISHED);
assertThat(claim("relay-b", NOW.plusSeconds(60))).isEmpty();
}
@Test
void aFailedRowIsNotClaimedAgainWithoutIntervention() {
OutboxRecord record = record();
appendInTransaction(record);
OutboxLease lease = claim("relay-a", NOW).getFirst();
repository.markFailed(lease, "INVALID_TOPIC", NOW);
assertThat(claim("relay-b", NOW.plusSeconds(60))).isEmpty();
}
@Test
void theRowAndTheBusinessChangeCommitTogetherOrNotAtAll() throws SQLException {
OutboxRecord record = record();
new org.springframework.jdbc.core.JdbcTemplate(dataSource)
.execute("CREATE TABLE IF NOT EXISTS orders (id TEXT PRIMARY KEY)");
// The interface method, inside a real Spring transaction that rolls back. This is the path
// business code takes; the old version called the Connection overload, which was never the
// one at risk.
try {
transactions.executeWithoutResult(
status -> {
new org.springframework.jdbc.core.JdbcTemplate(dataSource)
.execute("INSERT INTO orders (id) VALUES ('o-1')");
repository.append(record);
status.setRollbackOnly();
});
} catch (RuntimeException rolledBack) {
// setRollbackOnly is the mechanism; the rollback exception is not a failure here.
}
assertThat(repository.find(record.messageId()))
.as("a rolled back business change must not leave a publishable row")
.isEmpty();
}
@Test
void retentionRemovesOnlyPublishedRows() {
OutboxRecord published = record();
OutboxRecord pending = record();
appendInTransaction(published);
repository.markPublished(claim("relay-a", NOW).getFirst(), NOW);
appendInTransaction(pending);
int removed = repository.purgePublishedBefore(NOW.plusSeconds(1), 100);
assertThat(removed).isEqualTo(1);
assertThat(repository.find(pending.messageId())).isPresent();
}
/** Claims with an unlimited attempt budget, as a relay does on a row's first attempts. */
private List<OutboxLease> claim(String owner, Instant now) {
return repository.claimBatch(owner, 10, Duration.ofSeconds(30), now, Integer.MAX_VALUE);
}
private static OutboxRecord record() {
return record(
// The routing key is a column now, not a reserved header smuggled through the header map.
OutboxCanonicalMetadata.none().withRoutingKeys("acct-1", "acct-1"));
}
@Test
void aNewerRowWaitsWhileAnOlderRowWithTheSameOrderingKeyIsUnfinished() {
// given
OutboxRecord older = record(ordered("customer-42"), NOW.minusSeconds(60));
OutboxRecord newer = record(ordered("customer-42"), NOW.minusSeconds(30));
OutboxRecord otherKey = record(ordered("customer-7"), NOW.minusSeconds(30));
appendInTransaction(older);
appendInTransaction(newer);
appendInTransaction(otherKey);
// when
List<OutboxLease> claimed =
repository.claimBatch("relay-a", 10, Duration.ofSeconds(30), NOW, Integer.MAX_VALUE);
// then
assertThat(claimed)
.extracting(OutboxLease::messageId)
.as("a second relay, or a retry of the older row, would put the newer one first")
.containsExactlyInAnyOrder(older.messageId(), otherKey.messageId());
}
private static OutboxCanonicalMetadata ordered(String key) {
return OutboxCanonicalMetadata.none().withRoutingKeys(key, key);
}
private static OutboxRecord record(OutboxCanonicalMetadata metadata) {
return record(metadata, NOW.minusSeconds(60));
}
private static OutboxRecord record(OutboxCanonicalMetadata metadata, Instant createdAt) {
return new OutboxRecord(
MessageId.newId(),
new DestinationName("order-events"),
new MessageType("order.created"),
new SchemaVersion(1),
ContentType.JSON,
"{\"orderId\":\"o-1\"}".getBytes(StandardCharsets.UTF_8),
Map.of(),
metadata,
createdAt,
OutboxStatus.PENDING,
0,
Optional.empty(),
Optional.empty());
}
private static DataSource dataSource() {
PGSimpleDataSource source = new PGSimpleDataSource();
source.setUrl(POSTGRES.getJdbcUrl());
source.setUser(POSTGRES.getUsername());
source.setPassword(POSTGRES.getPassword());
return source;
}
/**
* Every migration in the module, in version order.
*
* <p>Discovered rather than listed. The list said V1 and V2 above a comment claiming it was every
* migration, so V3 and V4 were never applied here — and the first symptom of that was not a
* missing check but this suite failing against a column the production schema has. A test that
* applies part of the schema certifies a database nobody deploys.
*/
private static java.util.List<String> migrations() throws IOException {
java.net.URL directory =
OutboxPostgresIT.class.getClassLoader().getResource("db/migration/messaging");
if (directory == null) {
throw new IOException("the messaging migrations are missing from the classpath");
}
java.io.File[] files =
new java.io.File(java.net.URI.create(directory.toString()))
.listFiles((dir, name) -> name.endsWith(".sql"));
if (files == null || files.length == 0) {
throw new IOException("no migration applied; the schema under test would be empty");
}
java.util.List<String> names =
java.util.Arrays.stream(files).map(java.io.File::getName).sorted().toList();
java.util.List<String> statements = new java.util.ArrayList<>();
for (String name : names) {
statements.add(migration(name));
}
return statements;
}
private int countWhere(String predicate) {
try (Connection connection = dataSource.getConnection();
Statement statement = connection.createStatement();
java.sql.ResultSet results =
statement.executeQuery("SELECT count(*) FROM messaging_outbox WHERE " + predicate)) {
results.next();
return results.getInt(1);
} catch (SQLException failure) {
throw new IllegalStateException("could not count outbox rows", failure);
}
}
private String routingKeyOf(MessageId messageId) {
try (Connection connection = dataSource.getConnection();
java.sql.PreparedStatement statement =
connection.prepareStatement(
"SELECT routing_key FROM messaging_outbox WHERE message_id = ?")) {
statement.setObject(1, messageId.value());
try (java.sql.ResultSet results = statement.executeQuery()) {
results.next();
return results.getString(1);
}
} catch (SQLException failure) {
throw new IllegalStateException("could not read the routing key", failure);
}
}
private void execute(String sql) throws SQLException {
try (Connection connection = dataSource.getConnection();
Statement statement = connection.createStatement()) {
statement.execute(sql);
}
}
private static String migration(String fileName) throws IOException {
try (InputStream stream =
OutboxPostgresIT.class
.getClassLoader()
.getResourceAsStream("db/migration/messaging/" + fileName)) {
if (stream == null) {
throw new IOException("migration " + fileName + " is missing from the classpath");
}
return new String(stream.readAllBytes(), StandardCharsets.UTF_8);
}
}
@Test
void aSupersededRelayCannotOverwriteTheOutcomeOfTheOneThatReplacedIt() {
OutboxRecord record = record();
appendInTransaction(record);
// Relay A claims and stalls.
java.util.List<dev.caskeleton.messaging.reliability.OutboxLease> first =
repository.claimBatch("relay-a", 10, Duration.ofSeconds(30), NOW, Integer.MAX_VALUE);
assertThat(first).hasSize(1);
// The lease expires and relay B takes the row and publishes it.
java.util.List<dev.caskeleton.messaging.reliability.OutboxLease> second =
repository.claimBatch(
"relay-b", 10, Duration.ofSeconds(30), NOW.plusSeconds(31), Integer.MAX_VALUE);
assertThat(second).hasSize(1);
assertThat(second.get(0).token())
.as("every claim increments the token, which is what makes the older one detectable")
.isGreaterThan(first.get(0).token());
assertThat(repository.markPublished(second.get(0), NOW.plusSeconds(32)))
.isEqualTo(dev.caskeleton.messaging.reliability.OutboxTransitionResult.APPLIED);
// Relay A finally wakes up and tries to record its own outcome.
assertThat(
repository.markAmbiguous(
first.get(0), "CONFIRM_TIMEOUT", NOW.plusSeconds(40), NOW.plusSeconds(40)))
.as("this write used to succeed and made a published message claimable again")
.isEqualTo(dev.caskeleton.messaging.reliability.OutboxTransitionResult.STALE_LEASE);
assertThat(repository.find(record.messageId()).orElseThrow().status())
.isEqualTo(OutboxStatus.PUBLISHED);
}
@Test
void aDuplicateTerminalCallFromTheSameRelayIsRefused() {
OutboxRecord record = record();
appendInTransaction(record);
dev.caskeleton.messaging.reliability.OutboxLease lease =
repository.claimBatch("relay-a", 10, Duration.ofSeconds(30), NOW, Integer.MAX_VALUE).get(0);
assertThat(repository.markPublished(lease, NOW))
.isEqualTo(dev.caskeleton.messaging.reliability.OutboxTransitionResult.APPLIED);
assertThat(repository.markPublished(lease, NOW))
.as("the row is no longer IN_FLIGHT, so the second write has nothing to apply to")
.isEqualTo(dev.caskeleton.messaging.reliability.OutboxTransitionResult.STALE_LEASE);
}
@Test
void twoRelaysClaimingConcurrentlyGetDisjointRowsAndDistinctTokens() {
OutboxRecord one = record(OutboxCanonicalMetadata.none().withRoutingKeys("acct-1", "acct-1"));
OutboxRecord two = record(OutboxCanonicalMetadata.none().withRoutingKeys("acct-2", "acct-2"));
appendInTransaction(one);
appendInTransaction(two);
java.util.List<dev.caskeleton.messaging.reliability.OutboxLease> a =
repository.claimBatch("relay-a", 1, Duration.ofSeconds(30), NOW, Integer.MAX_VALUE);
java.util.List<dev.caskeleton.messaging.reliability.OutboxLease> b =
repository.claimBatch("relay-b", 1, Duration.ofSeconds(30), NOW, Integer.MAX_VALUE);
assertThat(a).hasSize(1);
assertThat(b).hasSize(1);
assertThat(a.get(0).messageId()).isNotEqualTo(b.get(0).messageId());
}
@Test
void anExpiryReclaimKeepsTheMessageIdAndAdvancesTheToken() {
OutboxRecord record = record();
appendInTransaction(record);
long firstToken =
repository
.claimBatch("relay-a", 10, Duration.ofSeconds(30), NOW, Integer.MAX_VALUE)
.get(0)
.token();
dev.caskeleton.messaging.reliability.OutboxLease reclaimed =
repository
.claimBatch(
"relay-b", 10, Duration.ofSeconds(30), NOW.plusSeconds(31), Integer.MAX_VALUE)
.get(0);
assertThat(reclaimed.messageId()).isEqualTo(record.messageId());
assertThat(reclaimed.token()).isEqualTo(firstToken + 1);
}
@Test
void anAmbiguousRowWaitsForItsBackoffBeforeItIsClaimedAgain() {
OutboxRecord record = record();
appendInTransaction(record);
dev.caskeleton.messaging.reliability.OutboxLease lease =
repository.claimBatch("relay-a", 10, Duration.ofSeconds(30), NOW, 10).get(0);
repository.markAmbiguous(lease, "CONFIRM_TIMEOUT", NOW, NOW.plusSeconds(120));
assertThat(repository.claimBatch("relay-a", 10, Duration.ofSeconds(30), NOW.plusSeconds(1), 10))
.as(
"an ambiguous row used to be claimable on the very next pass, so an outage republished"
+ " the whole backlog every poll interval")
.isEmpty();
assertThat(
repository.claimBatch("relay-a", 10, Duration.ofSeconds(30), NOW.plusSeconds(121), 10))
.hasSize(1);
}
@Test
void aRowOutOfAttemptsIsNotClaimedAgain() {
OutboxRecord record = record();
appendInTransaction(record);
Instant clock = NOW;
for (int attempt = 0; attempt < 3; attempt++) {
dev.caskeleton.messaging.reliability.OutboxLease lease =
repository.claimBatch("relay-a", 10, Duration.ofSeconds(30), clock, 3).get(0);
repository.markAmbiguous(lease, "CONFIRM_TIMEOUT", clock, clock);
clock = clock.plusSeconds(60);
}
assertThat(repository.claimBatch("relay-a", 10, Duration.ofSeconds(30), clock, 3))
.as("the configured budget was a number nothing consulted")
.isEmpty();
}
@Test
void anExhaustedRowIsDistinctFromARejectedOne() {
OutboxRecord record = record();
appendInTransaction(record);
dev.caskeleton.messaging.reliability.OutboxLease lease =
repository.claimBatch("relay-a", 10, Duration.ofSeconds(30), NOW, 10).get(0);
repository.markExhausted(lease, "budget spent without a confirmation", NOW);
assertThat(repository.find(record.messageId()).orElseThrow().status())
.as("'the broker refused this' and 'nobody ever answered' need different operator actions")
.isEqualTo(OutboxStatus.EXHAUSTED);
assertThat(
repository.claimBatch("relay-a", 10, Duration.ofSeconds(30), NOW.plusSeconds(600), 10))
.isEmpty();
}
@Test
void aConfirmedPublishClearsTheRetryClock() {
OutboxRecord record = record();
appendInTransaction(record);
dev.caskeleton.messaging.reliability.OutboxLease first =
repository.claimBatch("relay-a", 10, Duration.ofSeconds(30), NOW, 10).get(0);
repository.markAmbiguous(first, "CONFIRM_TIMEOUT", NOW, NOW.plusSeconds(60));
dev.caskeleton.messaging.reliability.OutboxLease second =
repository
.claimBatch("relay-a", 10, Duration.ofSeconds(30), NOW.plusSeconds(61), 10)
.get(0);
repository.markPublished(second, NOW.plusSeconds(62));
assertThat(repository.find(record.messageId()).orElseThrow().status())
.isEqualTo(OutboxStatus.PUBLISHED);
}
@Test
void everyCanonicalColumnRoundTripsThroughTheDatabase() {
MessageId cause = MessageId.newId();
OutboxCanonicalMetadata written =
new OutboxCanonicalMetadata(
Optional.of(new dev.caskeleton.messaging.api.ProducerId("order-api")),
Optional.of(NOW.minusSeconds(120)),
Optional.of(new dev.caskeleton.messaging.api.CorrelationId("checkout-7")),
Optional.of(new dev.caskeleton.messaging.api.CausationId(cause)),
Optional.of(new dev.caskeleton.messaging.api.TenantContext("acme")),
Optional.of("customer-42"),
Optional.of("customer-42"),
Optional.of("order.created-value"),
Optional.of("urn:schema:1"),
new dev.caskeleton.messaging.api.TraceContext(
Optional.of("00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"),
Optional.empty(),
Optional.empty()));
OutboxRecord record = record(written);
appendInTransaction(record);
assertThat(repository.find(record.messageId()).orElseThrow().metadata())
.as("what the relay reads back has to be what the business transaction wrote")
.isEqualTo(written);
}
@Test
void theRelayCanSelectOneTenantsBacklogWithoutDecodingAPayload() {
appendInTransaction(
record(
OutboxCanonicalMetadata.none()
.withTenant(new dev.caskeleton.messaging.api.TenantContext("acme"))));
appendInTransaction(
record(
OutboxCanonicalMetadata.none()
.withTenant(new dev.caskeleton.messaging.api.TenantContext("globex"))));
assertThat(countWhere("tenant = 'acme'"))
.as("the operational question an outbox backlog always raises, answerable as a SELECT")
.isEqualTo(1);
}
@Test
void theStoredRoutingKeyFallsBackToTheMessageId() {
OutboxRecord keyed =
record(OutboxCanonicalMetadata.none().withRoutingKeys("customer-42", "customer-42"));
OutboxRecord unkeyed = record(OutboxCanonicalMetadata.none());
appendInTransaction(keyed);
appendInTransaction(unkeyed);
assertThat(List.of(routingKeyOf(keyed.messageId()), routingKeyOf(unkeyed.messageId())))
.as("the fallback is stated once, in the column")
.containsExactly("customer-42", unkeyed.messageId().value().toString());
}
@Test
void aTenantThatBreaksTheSlugBoundIsRefusedByTheDatabase() {
org.assertj.core.api.Assertions.assertThatThrownBy(
() ->
execute(
"INSERT INTO messaging_outbox (message_id, destination, message_type, "
+ "schema_version, content_type, payload, created_at, status, attempts, "
+ "tenant) VALUES ('"
+ MessageId.newId().value()
+ "', 'order-events', 'order.created', 1, 'application/json', '\\x7b7d', "
+ "now(), 'PENDING', 0, 'Tenant With Spaces')"))
.as("a CDC connector and an operator both write this table without passing through Java")
.isInstanceOf(SQLException.class)
.hasMessageContaining("ck_messaging_outbox_tenant");
}
@Test
void aHeaderValueWithControlCharactersRoundTrips() {
OutboxRecord record =
new OutboxRecord(
MessageId.newId(),
new DestinationName("order-events"),
new MessageType("order.created"),
new SchemaVersion(1),
ContentType.JSON,
"{}".getBytes(StandardCharsets.UTF_8),
// A tab and a newline in a header value. Only backslash and quote were escaped, so
// this produced a document PostgreSQL refuses as invalid JSONB and the append failed
// with an error naming neither the header nor the row.
Map.of("x-note", "line one\nline\ttwo"),
OutboxCanonicalMetadata.none(),
NOW.minusSeconds(60),
OutboxStatus.PENDING,
0,
Optional.empty(),
Optional.empty());
appendInTransaction(record);
assertThat(repository.find(record.messageId()).orElseThrow().headers())
.containsEntry("x-note", "line one\nline\ttwo");
}
/**
* The hand-rolled reader took a quote preceded by a backslash for an escaped quote, so a value
* ending in an escaped backslash ran on into the next header and both came back wrong.
*/
@Test
void aHeaderValueEndingInABackslashRoundTripsWithoutSwallowingTheNextHeader() {
// given
OutboxRecord record =
new OutboxRecord(
MessageId.newId(),
new DestinationName("order-events"),
new MessageType("order.created"),
new SchemaVersion(1),
ContentType.JSON,
"{}".getBytes(StandardCharsets.UTF_8),
Map.of("x-path", "C:\\exports\\", "x-next", "after"),
OutboxCanonicalMetadata.none(),
NOW.minusSeconds(60),
OutboxStatus.PENDING,
0,
Optional.empty(),
Optional.empty());
appendInTransaction(record);
// when
Map<String, String> headers = repository.find(record.messageId()).orElseThrow().headers();
// then
assertThat(headers)
.containsExactlyInAnyOrderEntriesOf(Map.of("x-path", "C:\\exports\\", "x-next", "after"));
}
private void appendInTransaction(OutboxRecord record) {
transactions.executeWithoutResult(status -> repository.append(record));
}
}
@@ -0,0 +1,170 @@
package dev.caskeleton.messaging.inbox;
import dev.caskeleton.messaging.api.MessageId;
import dev.caskeleton.messaging.api.error.MessagingConfigurationException;
import dev.caskeleton.messaging.reliability.InboxRepository;
import java.sql.Connection;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Timestamp;
import java.time.Instant;
import java.util.Objects;
import javax.sql.DataSource;
import org.springframework.jdbc.datasource.DataSourceUtils;
import org.springframework.transaction.support.TransactionSynchronizationManager;
/**
* The PostgreSQL inbox.
*
* <p>Reservation is an {@code INSERT ... ON CONFLICT DO NOTHING} whose affected-row count is the
* answer: one means first delivery, zero means already processed. The composite primary key does
* the work, so there is no read-then-write race — two concurrent deliveries of the same message
* cannot both see "not processed" and both proceed.
*
* <p>The connection-taking overload is the one that matters. Reserving on a connection other than
* the one carrying the business write means the two commit independently, which reopens exactly the
* duplicate window the Inbox exists to close. The no-argument overload is provided only for
* retention sweeps and read-only queries.
*/
public final class JdbcInboxRepository implements InboxRepository {
private static final String RESERVE =
"""
INSERT INTO messaging_inbox (message_id, consumer_id, processed_at)
VALUES (?, ?, ?)
ON CONFLICT (message_id, consumer_id) DO NOTHING
""";
private final DataSource dataSource;
/**
* Creates a repository over a data source.
*
* @param dataSource the inbox data source
*/
public JdbcInboxRepository(DataSource dataSource) {
this.dataSource = Objects.requireNonNull(dataSource, "dataSource must not be null");
}
/**
* Reserves a message on the caller's transactional connection.
*
* <p>Package-private. It used to be public and was the only path that actually joined the
* caller's transaction, while the interface method — the one {@code IdempotentConsumer} calls —
* opened a raw connection that auto-commits. A reservation that commits on its own while the
* business side effect rolls back is a message that will never be redelivered and whose work
* never happened.
*
* @param connection the connection the business write is running on
* @param messageId the logical message identity
* @param consumerId the consumer's stable identity
* @param now the current instant
* @return true when this is the first time
*/
boolean reserve(Connection connection, MessageId messageId, String consumerId, Instant now) {
Objects.requireNonNull(connection, "connection must not be null");
Objects.requireNonNull(messageId, "messageId must not be null");
Objects.requireNonNull(now, "now must not be null");
if (consumerId == null || consumerId.isBlank()) {
throw new IllegalArgumentException("consumerId must not be blank");
}
try (PreparedStatement statement = connection.prepareStatement(RESERVE)) {
statement.setObject(1, messageId.value());
statement.setString(2, consumerId);
statement.setTimestamp(3, Timestamp.from(now));
return statement.executeUpdate() == 1;
} catch (SQLException exception) {
throw new MessagingConfigurationException(
"INBOX_RESERVE_FAILED", "could not reserve an inbox record", exception);
}
}
@Override
public boolean reserve(MessageId messageId, String consumerId, Instant now) {
requireActiveTransaction("reserving an inbox message");
Connection connection = DataSourceUtils.getConnection(dataSource);
try {
return reserve(connection, messageId, consumerId, now);
} finally {
DataSourceUtils.releaseConnection(connection, dataSource);
}
}
/**
* Refuses when there is no transaction to join, or when it cannot write.
*
* <p>The reservation and the side effect it guards have to commit or roll back together. Running
* the reservation on its own connection breaks that on the rollback path only — which is the path
* nobody exercises before production, and the one where the message is lost for good.
*/
private void requireActiveTransaction(String what) {
if (!TransactionSynchronizationManager.isActualTransactionActive()) {
throw new MessagingConfigurationException(
"INBOX_TRANSACTION_REQUIRED",
what
+ " requires an active transaction; a reservation that commits alone marks a message"
+ " processed whose work may still roll back");
}
if (TransactionSynchronizationManager.isCurrentTransactionReadOnly()) {
throw new MessagingConfigurationException(
"INBOX_TRANSACTION_REQUIRED",
what + " requires a writable transaction; the current one is read-only");
}
if (!TransactionSynchronizationManager.hasResource(dataSource)) {
throw new MessagingConfigurationException(
"INBOX_TRANSACTION_REQUIRED",
what
+ " requires the active transaction to be bound to this DataSource; it is bound to"
+ " another, so the reservation and the side effect would commit independently");
}
}
@Override
public boolean isProcessed(MessageId messageId, String consumerId) {
try (Connection connection = dataSource.getConnection();
PreparedStatement statement =
connection.prepareStatement(
"SELECT 1 FROM messaging_inbox WHERE message_id = ? AND consumer_id = ?")) {
statement.setObject(1, messageId.value());
statement.setString(2, consumerId);
try (ResultSet results = statement.executeQuery()) {
return results.next();
}
} catch (SQLException exception) {
throw new MessagingConfigurationException(
"INBOX_QUERY_FAILED", "could not query the inbox", exception);
}
}
@Override
public int purgeProcessedBefore(Instant processedBefore, int limit) {
Objects.requireNonNull(processedBefore, "processedBefore must not be null");
if (limit < 1) {
throw new IllegalArgumentException("a bounded purge deletes at least one row per call");
}
try (Connection connection = dataSource.getConnection();
PreparedStatement statement =
connection.prepareStatement(
"""
WITH expired AS (
SELECT message_id, consumer_id
FROM messaging_inbox
WHERE processed_at < ?
ORDER BY processed_at
LIMIT ?
FOR UPDATE SKIP LOCKED
)
DELETE FROM messaging_inbox i
USING expired e
WHERE i.message_id = e.message_id AND i.consumer_id = e.consumer_id
""")) {
statement.setTimestamp(1, Timestamp.from(processedBefore));
statement.setInt(2, limit);
return statement.executeUpdate();
} catch (SQLException exception) {
throw new MessagingConfigurationException(
"INBOX_PURGE_FAILED", "a bounded inbox purge failed", exception);
}
}
}
@@ -0,0 +1,326 @@
package dev.caskeleton.messaging.outbox;
import dev.caskeleton.messaging.admin.AdminOperationJournal;
import dev.caskeleton.messaging.admin.AdminOperationLease;
import dev.caskeleton.messaging.admin.AdminOperationRecord;
import dev.caskeleton.messaging.admin.AdminOperationState;
import dev.caskeleton.messaging.admin.PlanDigest;
import dev.caskeleton.messaging.api.error.MessageAuthorizationException;
import dev.caskeleton.messaging.api.error.MessagingConfigurationException;
import java.sql.Connection;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Timestamp;
import java.time.Duration;
import java.time.Instant;
import java.util.Objects;
import java.util.Optional;
import javax.sql.DataSource;
import org.springframework.jdbc.datasource.DataSourceUtils;
/**
* The shared, durable destructive-operation journal.
*
* <p>Lives beside the outbox because it needs the same thing the outbox needs and nothing more: one
* relational database that every replica can see. The uniqueness that stops a second execution is
* the primary key on {@code (approval_ticket, plan_digest)}, enforced by the database rather than
* by a check-then-act in application code — two replicas that read "no row" at the same instant
* would both proceed, and only the constraint makes exactly one of them win.
*
* <p>Takeover is conditional on the row still carrying the token the caller read. That is what
* fences a stalled runtime out: it wakes up holding token 3, the row is at token 4, and every write
* it attempts is refused rather than overwriting the replica that resumed the work.
*/
public final class JdbcAdminOperationJournal implements AdminOperationJournal {
private static final String SELECT =
"""
SELECT approval_ticket, plan_digest, operation_id, state, items_completed,
lease_owner, lease_token, lease_expires_at, started_at, finished_at, failure_code
FROM messaging_admin_operation
WHERE approval_ticket = ? AND plan_digest = ?
""";
private static final String INSERT =
"""
INSERT INTO messaging_admin_operation (
approval_ticket, plan_digest, operation_id, state, items_completed,
lease_owner, lease_token, lease_expires_at, started_at)
VALUES (?, ?, ?, 'STARTED', 0, ?, 1, ?, ?)
ON CONFLICT (approval_ticket, plan_digest) DO NOTHING
""";
private static final String TAKE_OVER =
"""
UPDATE messaging_admin_operation
SET operation_id = ?,
state = 'STARTED',
lease_owner = ?,
lease_token = lease_token + 1,
lease_expires_at = ?,
finished_at = NULL,
failure_code = NULL
WHERE approval_ticket = ?
AND plan_digest = ?
AND lease_token = ?
-- Only a failed operation or one whose lease ran out may be taken over. A live STARTED row
-- means another replica is executing it right now.
AND (state = 'FAILED' OR lease_expires_at <= ?)
RETURNING lease_token, items_completed
""";
private static final String CHECKPOINT =
"""
UPDATE messaging_admin_operation
SET items_completed = GREATEST(items_completed, ?),
lease_expires_at = ?
WHERE approval_ticket = ? AND plan_digest = ? AND lease_token = ?
""";
private static final String SETTLE =
"""
UPDATE messaging_admin_operation
SET state = ?,
items_completed = GREATEST(items_completed, ?),
finished_at = ?,
failure_code = ?
WHERE approval_ticket = ? AND plan_digest = ? AND lease_token = ?
""";
private final DataSource dataSource;
/**
* Creates the journal.
*
* @param dataSource the shared database every replica reads
*/
public JdbcAdminOperationJournal(DataSource dataSource) {
this.dataSource = Objects.requireNonNull(dataSource, "dataSource must not be null");
}
@Override
public AdminOperationLease begin(
String approvalTicket,
PlanDigest planDigest,
String operationId,
String leaseOwner,
Duration leaseDuration,
Instant now) {
Objects.requireNonNull(planDigest, "planDigest must not be null");
Objects.requireNonNull(leaseDuration, "leaseDuration must not be null");
Objects.requireNonNull(now, "now must not be null");
Instant expiry = now.plus(leaseDuration);
Connection connection = DataSourceUtils.getConnection(dataSource);
try {
if (insertClaim(
connection, approvalTicket, planDigest, operationId, leaseOwner, expiry, now)) {
return new AdminOperationLease(approvalTicket, planDigest, operationId, leaseOwner, 1L, 0);
}
AdminOperationRecord existing =
read(connection, approvalTicket, planDigest)
.orElseThrow(
() ->
new MessagingConfigurationException(
"ADMIN_JOURNAL_INCONSISTENT",
"the insert conflicted but no row exists for approval "
+ approvalTicket));
refuseIfNotResumable(existing, approvalTicket, now);
return takeOver(
connection, existing, approvalTicket, planDigest, operationId, leaseOwner, expiry, now);
} catch (SQLException failure) {
throw new MessagingConfigurationException(
"ADMIN_JOURNAL_UNAVAILABLE", "the operation journal could not be reached", failure);
} finally {
DataSourceUtils.releaseConnection(connection, dataSource);
}
}
private static void refuseIfNotResumable(
AdminOperationRecord existing, String approvalTicket, Instant now) {
if (existing.state() == AdminOperationState.COMPLETED) {
throw new MessageAuthorizationException(
"APPROVAL_ALREADY_EXECUTED",
("approval %s was already executed to completion at %s; an approval authorises one"
+ " execution, not a standing permission")
.formatted(approvalTicket, existing.finishedAt().orElse(existing.startedAt())));
}
if (existing.state() == AdminOperationState.STARTED
&& now.isBefore(existing.leaseExpiresAt())) {
throw new MessageAuthorizationException(
"ADMIN_OPERATION_IN_FLIGHT",
("approval %s is being executed by %s until at least %s; two runtimes executing one"
+ " approval is a duplicate storm, not a faster redrive")
.formatted(approvalTicket, existing.leaseOwner(), existing.leaseExpiresAt()));
}
}
private boolean insertClaim(
Connection connection,
String approvalTicket,
PlanDigest planDigest,
String operationId,
String leaseOwner,
Instant expiry,
Instant now)
throws SQLException {
try (PreparedStatement statement = connection.prepareStatement(INSERT)) {
statement.setString(1, approvalTicket);
statement.setString(2, planDigest.value());
statement.setString(3, operationId);
statement.setString(4, leaseOwner);
statement.setTimestamp(5, Timestamp.from(expiry));
statement.setTimestamp(6, Timestamp.from(now));
return statement.executeUpdate() == 1;
}
}
private AdminOperationLease takeOver(
Connection connection,
AdminOperationRecord existing,
String approvalTicket,
PlanDigest planDigest,
String operationId,
String leaseOwner,
Instant expiry,
Instant now)
throws SQLException {
try (PreparedStatement statement = connection.prepareStatement(TAKE_OVER)) {
statement.setString(1, operationId);
statement.setString(2, leaseOwner);
statement.setTimestamp(3, Timestamp.from(expiry));
statement.setString(4, approvalTicket);
statement.setString(5, planDigest.value());
statement.setLong(6, existing.leaseToken());
statement.setTimestamp(7, Timestamp.from(now));
try (ResultSet rows = statement.executeQuery()) {
if (!rows.next()) {
// Another replica took it over between the read and this update. Refusing is correct:
// exactly one runtime executes an approval, and it is not this one.
throw new MessageAuthorizationException(
"ADMIN_OPERATION_IN_FLIGHT",
"approval " + approvalTicket + " was taken over by another runtime");
}
return new AdminOperationLease(
approvalTicket,
planDigest,
operationId,
leaseOwner,
rows.getLong("lease_token"),
rows.getInt("items_completed"));
}
}
}
@Override
public void checkpoint(
AdminOperationLease lease, int itemsCompleted, Duration leaseDuration, Instant now) {
Objects.requireNonNull(lease, "lease must not be null");
Connection connection = DataSourceUtils.getConnection(dataSource);
try (PreparedStatement statement = connection.prepareStatement(CHECKPOINT)) {
statement.setInt(1, itemsCompleted);
statement.setTimestamp(2, Timestamp.from(now.plus(leaseDuration)));
statement.setString(3, lease.approvalTicket());
statement.setString(4, lease.planDigest().value());
statement.setLong(5, lease.leaseToken());
requireOwned(statement.executeUpdate(), lease);
} catch (SQLException failure) {
throw new MessagingConfigurationException(
"ADMIN_JOURNAL_UNAVAILABLE", "the operation journal could not be reached", failure);
} finally {
DataSourceUtils.releaseConnection(connection, dataSource);
}
}
@Override
public void complete(AdminOperationLease lease, int itemsCompleted, Instant now) {
settle(lease, AdminOperationState.COMPLETED, itemsCompleted, null, now);
}
@Override
public void fail(AdminOperationLease lease, int itemsCompleted, String failureCode, Instant now) {
Objects.requireNonNull(failureCode, "failureCode must not be null");
settle(lease, AdminOperationState.FAILED, itemsCompleted, failureCode, now);
}
private void settle(
AdminOperationLease lease,
AdminOperationState state,
int itemsCompleted,
String failureCode,
Instant now) {
Objects.requireNonNull(lease, "lease must not be null");
Connection connection = DataSourceUtils.getConnection(dataSource);
try (PreparedStatement statement = connection.prepareStatement(SETTLE)) {
statement.setString(1, state.name());
statement.setInt(2, itemsCompleted);
statement.setTimestamp(3, Timestamp.from(now));
statement.setString(4, failureCode);
statement.setString(5, lease.approvalTicket());
statement.setString(6, lease.planDigest().value());
statement.setLong(7, lease.leaseToken());
requireOwned(statement.executeUpdate(), lease);
} catch (SQLException failure) {
throw new MessagingConfigurationException(
"ADMIN_JOURNAL_UNAVAILABLE", "the operation journal could not be reached", failure);
} finally {
DataSourceUtils.releaseConnection(connection, dataSource);
}
}
private static void requireOwned(int updated, AdminOperationLease lease) {
if (updated == 1) {
return;
}
throw new MessageAuthorizationException(
"ADMIN_OPERATION_LEASE_LOST",
("this runtime no longer holds the lease on approval %s at token %d; another runtime took"
+ " the operation over and its progress must not be overwritten")
.formatted(lease.approvalTicket(), lease.leaseToken()));
}
@Override
public Optional<AdminOperationRecord> find(String approvalTicket, PlanDigest planDigest) {
Connection connection = DataSourceUtils.getConnection(dataSource);
try {
return read(connection, approvalTicket, planDigest);
} catch (SQLException failure) {
throw new MessagingConfigurationException(
"ADMIN_JOURNAL_UNAVAILABLE", "the operation journal could not be reached", failure);
} finally {
DataSourceUtils.releaseConnection(connection, dataSource);
}
}
private Optional<AdminOperationRecord> read(
Connection connection, String approvalTicket, PlanDigest planDigest) throws SQLException {
try (PreparedStatement statement = connection.prepareStatement(SELECT)) {
statement.setString(1, approvalTicket);
statement.setString(2, planDigest.value());
try (ResultSet rows = statement.executeQuery()) {
if (!rows.next()) {
return Optional.empty();
}
return Optional.of(
new AdminOperationRecord(
rows.getString("approval_ticket"),
new PlanDigest(rows.getString("plan_digest")),
rows.getString("operation_id"),
AdminOperationState.valueOf(rows.getString("state")),
rows.getInt("items_completed"),
rows.getString("lease_owner"),
rows.getLong("lease_token"),
rows.getTimestamp("lease_expires_at").toInstant(),
rows.getTimestamp("started_at").toInstant(),
Optional.ofNullable(rows.getTimestamp("finished_at")).map(Timestamp::toInstant),
Optional.ofNullable(rows.getString("failure_code"))));
}
}
}
@Override
public boolean isDurable() {
return true;
}
}
@@ -0,0 +1,527 @@
package dev.caskeleton.messaging.outbox;
import dev.caskeleton.messaging.api.CausationId;
import dev.caskeleton.messaging.api.ContentType;
import dev.caskeleton.messaging.api.CorrelationId;
import dev.caskeleton.messaging.api.MessageId;
import dev.caskeleton.messaging.api.MessageType;
import dev.caskeleton.messaging.api.ProducerId;
import dev.caskeleton.messaging.api.SchemaVersion;
import dev.caskeleton.messaging.api.TenantContext;
import dev.caskeleton.messaging.api.TraceContext;
import dev.caskeleton.messaging.api.destination.DestinationName;
import dev.caskeleton.messaging.api.error.MessagingConfigurationException;
import dev.caskeleton.messaging.reliability.OutboxCanonicalMetadata;
import dev.caskeleton.messaging.reliability.OutboxLease;
import dev.caskeleton.messaging.reliability.OutboxRecord;
import dev.caskeleton.messaging.reliability.OutboxRepository;
import dev.caskeleton.messaging.reliability.OutboxStatus;
import dev.caskeleton.messaging.reliability.OutboxTransitionResult;
import java.sql.Array;
import java.sql.Connection;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Timestamp;
import java.time.Duration;
import java.time.Instant;
import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Objects;
import java.util.Optional;
import javax.sql.DataSource;
import org.springframework.jdbc.datasource.DataSourceUtils;
import org.springframework.transaction.support.TransactionSynchronizationManager;
/**
* The PostgreSQL outbox.
*
* <p>{@link #append} deliberately takes no connection of its own: it uses the one the caller is
* already inside, which is the entire mechanism. An outbox row written on a separate connection
* commits independently of the business change and reopens the window the pattern exists to close.
*
* <p>Claiming uses {@code SELECT ... FOR UPDATE SKIP LOCKED}. Two relay instances polling the same
* table would otherwise both claim the same rows and publish them twice; {@code SKIP LOCKED} lets
* the second instance step over what the first already holds instead of blocking behind it.
*/
public final class JdbcOutboxRepository implements OutboxRepository {
private static final String INSERT =
"""
INSERT INTO messaging_outbox (
message_id, destination, message_type, schema_version, content_type,
payload, headers, created_at, status, attempts,
producer, occurred_at, correlation_id, causation_id, tenant,
partition_key, ordering_key, schema_subject, schema_uri,
traceparent, tracestate, baggage)
VALUES (?, ?, ?, ?, ?, ?, jsonb_object(?::text[]), ?, ?, ?,
?, ?, ?, ?, ?,
?, ?, ?, ?,
?, ?, ?)
""";
/**
* The columns every read of a row selects.
*
* <p>One constant rather than four copies of the list. The lease, claim, find and reclaim
* statements each spelled it out, and a column added to one of them and not the others is a
* message that arrives with its tenant on the claim path and without it on the lease path — a
* difference that shows up as a data bug in whichever consumer happened to be reading.
*/
private static final String COLUMNS =
"""
message_id, destination, message_type, schema_version, content_type,
payload,
ARRAY(SELECT h.key FROM jsonb_each_text(headers) h ORDER BY h.key) AS header_keys,
ARRAY(SELECT h.value FROM jsonb_each_text(headers) h ORDER BY h.key) AS header_values,
created_at, status, attempts, lease_expires_at, last_failure_code,
producer, occurred_at, correlation_id, causation_id, tenant,
partition_key, ordering_key, schema_subject, schema_uri,
traceparent, tracestate, baggage\
""";
/**
* The claim that records who holds the row and increments its fencing token.
*
* <p>The token increments on the server inside the same statement that grants the claim, so two
* relays racing for the same row cannot receive the same number.
*/
private static final String CLAIM =
"""
WITH claimable AS (
SELECT m.message_id
FROM messaging_outbox m
WHERE m.status IN ('PENDING', 'AMBIGUOUS', 'IN_FLIGHT')
AND (m.lease_expires_at IS NULL OR m.lease_expires_at <= ?)
-- The retry clock lives in the row, not in the relay's memory. Without these two
-- predicates an AMBIGUOUS row became claimable again on the very next pass, so a
-- broker outage meant the whole backlog was republished every poll interval and the
-- configured attempt budget was a number nothing consulted.
AND (m.next_attempt_at IS NULL OR m.next_attempt_at <= ?)
AND m.attempts < ?
-- A row with an ordering key waits while an older row with the same key is still
-- unfinished. SKIP LOCKED let a second relay take the newer row while the first still
-- held the older one, and an AMBIGUOUS older row was retried after newer ones had
-- already gone out. md5 matches the partial index, which cannot hold a key that long.
AND (m.ordering_key IS NULL OR NOT EXISTS (
SELECT 1
FROM messaging_outbox older
WHERE older.destination = m.destination
AND md5(older.ordering_key) = md5(m.ordering_key)
AND older.ordering_key = m.ordering_key
AND older.status IN ('PENDING', 'AMBIGUOUS', 'IN_FLIGHT')
AND (older.created_at, older.message_id) < (m.created_at, m.message_id)))
ORDER BY m.created_at, m.message_id
LIMIT ?
FOR UPDATE SKIP LOCKED
)
UPDATE messaging_outbox o
SET status = 'IN_FLIGHT',
lease_expires_at = ?,
lease_owner = ?,
lease_token = o.lease_token + 1
FROM claimable c
WHERE o.message_id = c.message_id
RETURNING o.message_id, o.destination, o.message_type, o.schema_version, o.content_type,
o.payload,
ARRAY(SELECT h.key FROM jsonb_each_text(o.headers) h ORDER BY h.key) AS header_keys,
ARRAY(SELECT h.value FROM jsonb_each_text(o.headers) h ORDER BY h.key)
AS header_values,
o.created_at, o.status, o.attempts,
o.lease_expires_at, o.last_failure_code, o.lease_owner, o.lease_token,
o.producer, o.occurred_at, o.correlation_id, o.causation_id, o.tenant,
o.partition_key, o.ordering_key, o.schema_subject, o.schema_uri,
o.traceparent, o.tracestate, o.baggage
""";
private final DataSource dataSource;
/**
* Creates a repository over a data source.
*
* @param dataSource the outbox data source
*/
public JdbcOutboxRepository(DataSource dataSource) {
this.dataSource = Objects.requireNonNull(dataSource, "dataSource must not be null");
}
/**
* Appends a record on an existing connection.
*
* <p>Package-private. It used to be the public overload "business code should use", which meant
* the safe path was the one a caller had to know about and the interface method — the one the
* port documents — opened its own connection. Handing a {@code Connection} across a reliability
* API also makes the transaction the caller's problem to remember; {@link #append(OutboxRecord)}
* now joins the caller's transaction itself and refuses when there is none.
*
* @param connection the caller's transactional connection
* @param record the record to write
*/
void append(Connection connection, OutboxRecord record) {
Objects.requireNonNull(connection, "connection must not be null");
Objects.requireNonNull(record, "record must not be null");
try (PreparedStatement statement = connection.prepareStatement(INSERT)) {
statement.setObject(1, record.messageId().value());
statement.setString(2, record.destination().value());
statement.setString(3, record.messageType().value());
statement.setInt(4, record.schemaVersion().value());
statement.setString(5, record.contentType().value());
statement.setBytes(6, record.payload());
statement.setArray(7, connection.createArrayOf("text", flatten(record.headers())));
statement.setTimestamp(8, Timestamp.from(record.createdAt()));
statement.setString(9, record.status().name());
statement.setInt(10, record.attempts());
OutboxCanonicalMetadata metadata = record.metadata();
statement.setString(11, metadata.producer().map(ProducerId::value).orElse(null));
statement.setTimestamp(12, metadata.occurredAt().map(Timestamp::from).orElse(null));
statement.setString(13, metadata.correlationId().map(CorrelationId::value).orElse(null));
statement.setObject(
14, metadata.causationId().map(causation -> causation.value().value()).orElse(null));
statement.setString(15, metadata.tenant().map(TenantContext::tenantId).orElse(null));
statement.setString(16, metadata.partitionKey().orElse(null));
statement.setString(17, metadata.orderingKey().orElse(null));
statement.setString(18, metadata.schemaSubject().orElse(null));
statement.setString(19, metadata.schemaUri().orElse(null));
statement.setString(20, metadata.traceContext().traceparent().orElse(null));
statement.setString(21, metadata.traceContext().tracestate().orElse(null));
statement.setString(22, metadata.traceContext().baggage().orElse(null));
statement.executeUpdate();
} catch (SQLException exception) {
throw new MessagingConfigurationException(
"OUTBOX_APPEND_FAILED", "could not append an outbox record", exception);
}
}
@Override
public void append(OutboxRecord record) {
Objects.requireNonNull(record, "record must not be null");
// The port says this runs inside the caller's business transaction. It did not: it opened a raw
// connection from the pool, which auto-commits independently — so a business transaction that
// rolled back afterwards left the event behind and the relay published a change that never
// happened.
requireActiveTransaction("OUTBOX_TRANSACTION_REQUIRED", "appending to the outbox");
Connection connection = DataSourceUtils.getConnection(dataSource);
try {
append(connection, record);
} finally {
// Releases only when the connection is not the transaction's; when it is, this is a no-op and
// the caller's commit or rollback decides what happens to the row.
DataSourceUtils.releaseConnection(connection, dataSource);
}
}
/**
* Refuses when there is no transaction to join, or when it cannot write.
*
* <p>Fail-fast rather than "work anyway": an append that silently runs outside the caller's
* transaction produces exactly the ghost publication this repository exists to prevent, and it
* produces it only on the rollback path — which is the path nobody exercises before production.
*/
private void requireActiveTransaction(String code, String what) {
if (!TransactionSynchronizationManager.isActualTransactionActive()) {
throw new MessagingConfigurationException(
code,
what
+ " requires an active transaction; without one the row commits on its own and a"
+ " later rollback of the business change leaves it behind");
}
if (TransactionSynchronizationManager.isCurrentTransactionReadOnly()) {
throw new MessagingConfigurationException(
code, what + " requires a writable transaction; the current one is read-only");
}
if (!TransactionSynchronizationManager.hasResource(dataSource)) {
throw new MessagingConfigurationException(
code,
what
+ " requires the active transaction to be bound to this DataSource; it is bound to"
+ " another, so the two would commit independently");
}
}
@Override
public List<OutboxLease> claimBatch(
String owner, int batchSize, Duration leaseDuration, Instant now, int maxAttempts) {
Objects.requireNonNull(owner, "owner must not be null");
Objects.requireNonNull(leaseDuration, "leaseDuration must not be null");
Objects.requireNonNull(now, "now must not be null");
Instant expiresAt = now.plus(leaseDuration);
return withConnection(
connection -> {
List<OutboxLease> claimed = new ArrayList<>();
try (PreparedStatement statement = connection.prepareStatement(CLAIM)) {
statement.setTimestamp(1, Timestamp.from(now));
statement.setTimestamp(2, Timestamp.from(now));
statement.setInt(3, maxAttempts);
statement.setInt(4, batchSize);
statement.setTimestamp(5, Timestamp.from(expiresAt));
statement.setString(6, owner);
try (ResultSet results = statement.executeQuery()) {
while (results.next()) {
claimed.add(
new OutboxLease(
read(results),
results.getString("lease_owner"),
results.getLong("lease_token"),
expiresAt));
}
}
}
return List.copyOf(claimed);
});
}
@Override
public OutboxTransitionResult markPublished(OutboxLease lease, Instant now) {
return transition(
lease,
"UPDATE messaging_outbox SET status = 'PUBLISHED', published_at = ?, "
+ "lease_expires_at = NULL, lease_owner = NULL, next_attempt_at = NULL, "
+ "attempts = attempts + 1 ",
now,
null);
}
@Override
public OutboxTransitionResult markAmbiguous(
OutboxLease lease, String failureCode, Instant now, Instant nextAttemptAt) {
Objects.requireNonNull(nextAttemptAt, "nextAttemptAt must not be null");
// The backoff the policy computed is written onto the row. Keeping it in the relay's memory
// means a restart forgets it, and every relay computes its own — so the same row is retried by
// as many workers as there are replicas, as fast as they poll.
return transitionWithNextAttempt(
lease,
"UPDATE messaging_outbox SET status = 'AMBIGUOUS', lease_expires_at = NULL, "
+ "lease_owner = NULL, last_failure_code = ?, attempts = attempts + 1, "
+ "next_attempt_at = ? ",
failureCode,
nextAttemptAt);
}
@Override
public OutboxTransitionResult markExhausted(OutboxLease lease, String reason, Instant now) {
return transition(
lease,
"UPDATE messaging_outbox SET status = 'EXHAUSTED', lease_expires_at = NULL, "
+ "lease_owner = NULL, last_failure_code = ?, attempts = attempts + 1 ",
now,
reason);
}
private OutboxTransitionResult transitionWithNextAttempt(
OutboxLease lease, String setClause, String failureCode, Instant nextAttemptAt) {
Objects.requireNonNull(lease, "lease must not be null");
String sql =
setClause
+ "WHERE message_id = ? AND status = 'IN_FLIGHT' AND lease_owner = ? AND lease_token ="
+ " ?";
return withConnection(
connection -> {
try (PreparedStatement statement = connection.prepareStatement(sql)) {
statement.setString(1, failureCode);
statement.setTimestamp(2, Timestamp.from(nextAttemptAt));
statement.setObject(3, lease.messageId().value());
statement.setString(4, lease.owner());
statement.setLong(5, lease.token());
return statement.executeUpdate() == 1
? OutboxTransitionResult.APPLIED
: OutboxTransitionResult.STALE_LEASE;
}
});
}
@Override
public OutboxTransitionResult markFailed(OutboxLease lease, String failureCode, Instant now) {
return transition(
lease,
"UPDATE messaging_outbox SET status = 'FAILED', lease_expires_at = NULL, "
+ "lease_owner = NULL, last_failure_code = ?, attempts = attempts + 1 ",
now,
failureCode);
}
@Override
public OutboxTransitionResult releaseLease(OutboxLease lease) {
return transition(
lease,
"UPDATE messaging_outbox SET status = 'PENDING', lease_expires_at = NULL, "
+ "lease_owner = NULL ",
null,
null);
}
/**
* Applies a terminal write, but only to the row this lease still owns.
*
* <p>The predicate carries the owner and the token as well as the id, so a relay that stalled
* past its lease writes nothing: another relay's claim incremented the token, and this update
* matches zero rows. Zero is reported rather than swallowed — a stale write means this worker may
* have produced a duplicate publication, which is exactly what an operator needs to see.
*/
private OutboxTransitionResult transition(
OutboxLease lease, String setClause, Instant now, String failureCode) {
Objects.requireNonNull(lease, "lease must not be null");
String sql =
setClause
+ "WHERE message_id = ? AND status = 'IN_FLIGHT' AND lease_owner = ? AND lease_token ="
+ " ?";
return withConnection(
connection -> {
try (PreparedStatement statement = connection.prepareStatement(sql)) {
int index = 1;
if (failureCode != null) {
statement.setString(index++, failureCode);
} else if (now != null) {
statement.setTimestamp(index++, Timestamp.from(now));
}
statement.setObject(index++, lease.messageId().value());
statement.setString(index++, lease.owner());
statement.setLong(index, lease.token());
return statement.executeUpdate() == 1
? OutboxTransitionResult.APPLIED
: OutboxTransitionResult.STALE_LEASE;
}
});
}
@Override
public Optional<OutboxRecord> find(MessageId messageId) {
return withConnection(
connection -> {
try (PreparedStatement statement =
connection.prepareStatement(
"SELECT " + COLUMNS + " FROM messaging_outbox WHERE message_id = ?")) {
statement.setObject(1, messageId.value());
try (ResultSet results = statement.executeQuery()) {
return results.next() ? Optional.of(read(results)) : Optional.<OutboxRecord>empty();
}
}
});
}
@Override
public int purgePublishedBefore(Instant publishedBefore, int limit) {
Objects.requireNonNull(publishedBefore, "publishedBefore must not be null");
if (limit < 1) {
throw new IllegalArgumentException("a bounded purge deletes at least one row per call");
}
// The CTE picks a bounded set of ids with SKIP LOCKED and deletes exactly those. An unbounded
// DELETE holds locks and writes WAL in proportion to the whole backlog, which stalls the relay
// and the business writes behind retention.
return withConnection(
connection -> {
try (PreparedStatement statement =
connection.prepareStatement(
"""
WITH expired AS (
SELECT message_id
FROM messaging_outbox
WHERE status = 'PUBLISHED' AND published_at < ?
ORDER BY published_at
LIMIT ?
FOR UPDATE SKIP LOCKED
)
DELETE FROM messaging_outbox o
USING expired e
WHERE o.message_id = e.message_id
""")) {
statement.setTimestamp(1, Timestamp.from(publishedBefore));
statement.setInt(2, limit);
return statement.executeUpdate();
}
});
}
private static OutboxRecord read(ResultSet results) throws SQLException {
Timestamp lease = results.getTimestamp("lease_expires_at");
return new OutboxRecord(
new MessageId(results.getObject("message_id", java.util.UUID.class)),
new DestinationName(results.getString("destination")),
new MessageType(results.getString("message_type")),
new SchemaVersion(results.getInt("schema_version")),
new ContentType(results.getString("content_type")),
results.getBytes("payload"),
headers(results.getArray("header_keys"), results.getArray("header_values")),
readMetadata(results),
results.getTimestamp("created_at").toInstant(),
OutboxStatus.valueOf(results.getString("status")),
results.getInt("attempts"),
Optional.ofNullable(lease).map(Timestamp::toInstant),
Optional.ofNullable(results.getString("last_failure_code")));
}
/**
* Rebuilds the canonical metadata from the row's own columns.
*
* <p>Absent columns stay absent. A row written before the columns existed rebuilds with empty
* metadata, which is the same thing a row written by a producer that had none rebuilds with — and
* the reader's behaviour has to be identical in both cases, because guessing a tenant or a
* correlation is worse than carrying none.
*/
private static OutboxCanonicalMetadata readMetadata(ResultSet results) throws SQLException {
Timestamp occurredAt = results.getTimestamp("occurred_at");
java.util.UUID causation = results.getObject("causation_id", java.util.UUID.class);
return new OutboxCanonicalMetadata(
Optional.ofNullable(results.getString("producer")).map(ProducerId::new),
Optional.ofNullable(occurredAt).map(Timestamp::toInstant),
Optional.ofNullable(results.getString("correlation_id")).map(CorrelationId::new),
Optional.ofNullable(causation).map(value -> new CausationId(new MessageId(value))),
Optional.ofNullable(results.getString("tenant")).map(TenantContext::new),
Optional.ofNullable(results.getString("partition_key")),
Optional.ofNullable(results.getString("ordering_key")),
Optional.ofNullable(results.getString("schema_subject")),
Optional.ofNullable(results.getString("schema_uri")),
new TraceContext(
Optional.ofNullable(results.getString("traceparent")),
Optional.ofNullable(results.getString("tracestate")),
Optional.ofNullable(results.getString("baggage"))));
}
private <T> T withConnection(ConnectionCallback<T> callback) {
try (Connection connection = dataSource.getConnection()) {
return callback.apply(connection);
} catch (SQLException exception) {
throw new MessagingConfigurationException(
"OUTBOX_QUERY_FAILED", "an outbox query failed", exception);
}
}
/**
* The headers as one flat key, value, key, value array for {@code jsonb_object(text[])}.
*
* <p>PostgreSQL builds and escapes the JSON. The hand-rolled writer and reader this replaces got
* the escaping right one way and wrong the other: the reader took a quote after an escaped
* backslash for an escaped quote, so a value ending in a backslash ran on into the next header.
*/
private static String[] flatten(Map<String, String> headers) {
String[] flat = new String[headers.size() * 2];
int index = 0;
for (Map.Entry<String, String> entry : headers.entrySet()) {
flat[index++] = entry.getKey();
flat[index++] = entry.getValue();
}
return flat;
}
/** Rebuilds the headers from the aligned key and value arrays the reads select. */
private static Map<String, String> headers(Array keys, Array values) throws SQLException {
Map<String, String> headers = new LinkedHashMap<>();
if (keys == null || values == null) {
return headers;
}
String[] names = (String[]) keys.getArray();
String[] texts = (String[]) values.getArray();
for (int index = 0; index < names.length; index++) {
headers.put(names[index], texts[index]);
}
return headers;
}
/** A unit of work against a borrowed connection. */
@FunctionalInterface
private interface ConnectionCallback<T> {
T apply(Connection connection) throws SQLException;
}
}
@@ -0,0 +1,41 @@
-- Transactional outbox.
--
-- Written by the business transaction, drained by the relay. message_id is the primary key rather
-- than a surrogate: it is the logical identity the relay must preserve across every retry, and
-- making it the key means no code path can accidentally publish the same row under a new id.
CREATE TABLE messaging_outbox
(
message_id UUID NOT NULL,
destination VARCHAR(160) NOT NULL,
message_type VARCHAR(240) NOT NULL,
schema_version INTEGER NOT NULL,
content_type VARCHAR(160) NOT NULL,
payload BYTEA NOT NULL,
headers JSONB NOT NULL DEFAULT '{}'::JSONB,
created_at TIMESTAMPTZ NOT NULL,
status VARCHAR(16) NOT NULL,
attempts INTEGER NOT NULL DEFAULT 0,
lease_expires_at TIMESTAMPTZ,
published_at TIMESTAMPTZ,
last_failure_code VARCHAR(120),
CONSTRAINT pk_messaging_outbox PRIMARY KEY (message_id),
CONSTRAINT ck_messaging_outbox_status
CHECK (status IN ('PENDING', 'IN_FLIGHT', 'PUBLISHED', 'AMBIGUOUS', 'FAILED')),
CONSTRAINT ck_messaging_outbox_attempts CHECK (attempts >= 0),
CONSTRAINT ck_messaging_outbox_schema_version CHECK (schema_version >= 1)
);
-- The relay's only hot query: claim the oldest rows that are publishable and unleased. The partial
-- index keeps it proportional to the backlog rather than to the table, which matters because
-- PUBLISHED rows accumulate until the retention job removes them.
--
-- IN_FLIGHT is included. A relay that dies mid-publish leaves rows in that state, and their lease
-- expiry is what makes them claimable again; omitting them here would strand those messages.
CREATE INDEX ix_messaging_outbox_claimable
ON messaging_outbox (created_at)
WHERE status IN ('PENDING', 'AMBIGUOUS', 'IN_FLIGHT');
-- Retention sweeps read this.
CREATE INDEX ix_messaging_outbox_published_at
ON messaging_outbox (published_at)
WHERE status = 'PUBLISHED';
@@ -0,0 +1,39 @@
-- Lease owner and fencing token.
--
-- V1 recorded only lease_expires_at, so a claim said when it would end and nothing about who held
-- it. The relay's terminal writes matched on message_id alone, which means a worker that stalled
-- past its lease could still write:
--
-- relay A claims the row and calls the broker
-- the lease expires; relay B reclaims it, publishes, and records PUBLISHED
-- relay A finally times out and records AMBIGUOUS over the top
--
-- The row is now claimable again and the message is published a second time. Making the lease
-- longer than the publish timeout lowers the odds; it does not turn a GC pause, a scheduler stall
-- or a slow broker into a data constraint. A token does: every terminal write names the
-- acquisition it belongs to, and a superseded worker's write matches nothing.
ALTER TABLE messaging_outbox
ADD COLUMN lease_owner VARCHAR(160),
ADD COLUMN lease_token BIGINT NOT NULL DEFAULT 0,
ADD COLUMN next_attempt_at TIMESTAMPTZ;
-- Backfill is unnecessary for correctness — the default is 0 and the first claim increments it —
-- but the constraint states the invariant the code depends on.
ALTER TABLE messaging_outbox
ADD CONSTRAINT ck_messaging_outbox_lease_token CHECK (lease_token >= 0);
-- EXHAUSTED is a new terminal state: the attempt budget ran out without any confirmation, which is
-- not the same as the broker rejecting the message. V1's CHECK listed five states, so writing the
-- sixth failed at the constraint rather than at review.
ALTER TABLE messaging_outbox
DROP CONSTRAINT ck_messaging_outbox_status;
ALTER TABLE messaging_outbox
ADD CONSTRAINT ck_messaging_outbox_status
CHECK (status IN ('PENDING', 'IN_FLIGHT', 'PUBLISHED', 'AMBIGUOUS', 'FAILED', 'EXHAUSTED'));
-- The claim predicate now filters on next_attempt_at as well, so the partial index has to carry it
-- or every poll degrades into a scan of the backlog once rows start backing off.
CREATE INDEX ix_messaging_outbox_next_attempt
ON messaging_outbox (next_attempt_at, created_at)
WHERE status IN ('PENDING', 'AMBIGUOUS', 'IN_FLIGHT');
@@ -0,0 +1,37 @@
-- The destructive-operation journal.
--
-- Keyed on (approval_ticket, plan_digest) rather than the ticket alone: the ticket alone cannot
-- distinguish "this approval already ran" from "this approval is being presented for a different
-- plan", and those need opposite answers. The primary key is what makes two replicas racing for the
-- same approval resolve to one winner rather than two executions.
--
-- lease_owner/lease_token/lease_expires_at are the same fencing pattern the outbox uses: a runtime
-- that stalls past its lease loses it, and its later writes are refused because its token is stale.
-- items_completed is the resume point — without it a retry after a crash republishes everything the
-- first attempt already moved.
CREATE TABLE IF NOT EXISTS messaging_admin_operation (
approval_ticket VARCHAR(200) NOT NULL,
plan_digest CHAR(64) NOT NULL,
operation_id VARCHAR(200) NOT NULL,
state VARCHAR(20) NOT NULL,
items_completed INTEGER NOT NULL DEFAULT 0,
lease_owner VARCHAR(200) NOT NULL,
lease_token BIGINT NOT NULL DEFAULT 1,
lease_expires_at TIMESTAMPTZ NOT NULL,
started_at TIMESTAMPTZ NOT NULL,
finished_at TIMESTAMPTZ,
failure_code VARCHAR(200),
CONSTRAINT pk_messaging_admin_operation PRIMARY KEY (approval_ticket, plan_digest),
CONSTRAINT ck_messaging_admin_operation_state
CHECK (state IN ('STARTED', 'COMPLETED', 'FAILED')),
CONSTRAINT ck_messaging_admin_operation_items CHECK (items_completed >= 0),
CONSTRAINT ck_messaging_admin_operation_token CHECK (lease_token >= 1),
CONSTRAINT ck_messaging_admin_operation_digest CHECK (plan_digest ~ '^[0-9a-f]{64}$')
);
-- Answers "which operations are in flight right now", the question an operator asks when a redrive
-- appears stuck and they are deciding whether to take it over.
CREATE INDEX IF NOT EXISTS ix_messaging_admin_operation_live
ON messaging_admin_operation (lease_expires_at)
WHERE state = 'STARTED';
@@ -0,0 +1,66 @@
-- The envelope's canonical facts, as columns.
--
-- V1 stored identity, type, version, content type, payload and a free-form header map. Everything
-- else the envelope carries — producer, tenant, correlation, causation, the routing keys, the
-- schema the payload was written against, the active trace — had nowhere to go, so it was either
-- lost when the relay rebuilt the envelope or smuggled through the header map under the reserved
-- `msg.*` names the platform is supposed to own. Smuggling is the worse of the two: a row whose
-- header map contains `msg.id` overwrites another message's identity on the wire, and the consumer
-- trusts the last such header it sees.
--
-- Columns rather than a versioned envelope blob. Both round-trip the values faithfully; only one of
-- them lets the relay answer an operator's questions. "Which tenant is the backlog for", "which
-- correlation is stuck", "which rows carry a schema this consumer cannot read" are SELECTs against
-- this table if the fields are columns, and payload decoding of the whole backlog if they are not.
--
-- Every column is nullable. A row written before this migration has none of them, and a producer
-- that genuinely has no correlation writes none either; the reader treats both the same way, which
-- is to carry what is there and invent nothing.
ALTER TABLE messaging_outbox
ADD COLUMN producer VARCHAR(120),
ADD COLUMN occurred_at TIMESTAMPTZ,
ADD COLUMN correlation_id VARCHAR(160),
ADD COLUMN causation_id UUID,
ADD COLUMN tenant VARCHAR(64),
ADD COLUMN partition_key VARCHAR(1024),
ADD COLUMN ordering_key VARCHAR(1024),
ADD COLUMN schema_subject VARCHAR(240),
ADD COLUMN schema_uri VARCHAR(1024),
ADD COLUMN traceparent VARCHAR(64),
ADD COLUMN tracestate VARCHAR(512),
ADD COLUMN baggage VARCHAR(8192);
-- The same bound TenantContext enforces in Java. Stated here as well because the relay, the CDC
-- connector and any operator query read this table directly: a tenant slug that only the
-- application validates is a tenant slug that an INSERT from anywhere else can violate, and a
-- tenant id is the field every downstream authorization decision reads.
ALTER TABLE messaging_outbox
ADD CONSTRAINT ck_messaging_outbox_tenant
CHECK (tenant IS NULL OR tenant ~ '^[a-z0-9][a-z0-9._-]{0,63}$');
-- A schema location with no subject cannot be resolved: the reader would hold a URI and no way to
-- know what it is a schema for.
ALTER TABLE messaging_outbox
ADD CONSTRAINT ck_messaging_outbox_schema_reference
CHECK (schema_uri IS NULL OR schema_subject IS NOT NULL);
-- "Which tenant is the backlog for" is the first question asked when an outbox stops draining, and
-- before this column it could only be answered by decoding every payload. Partial, like the other
-- outbox indexes, because PUBLISHED rows accumulate until retention removes them and no operator
-- asks that question about work that already left.
CREATE INDEX ix_messaging_outbox_tenant_backlog
ON messaging_outbox (tenant, created_at)
WHERE status IN ('PENDING', 'AMBIGUOUS', 'IN_FLIGHT');
-- The key a relay puts on the wire, computed once and stored, so both relays agree.
--
-- Debezium's Event Router takes the message key from a column. It was pointed at `destination`,
-- which made the key the topic name — every message on a topic sharing one key, so every message
-- landing on one partition, and keyed ordering meaning nothing. The polling relay meanwhile used
-- the partition key when the row had one and the message id when it did not.
--
-- A generated column states that fallback once, in the place both relays read, instead of leaving
-- it as a rule each of them implements separately and one of them gets wrong.
ALTER TABLE messaging_outbox
ADD COLUMN routing_key TEXT
GENERATED ALWAYS AS (COALESCE(partition_key, message_id::TEXT)) STORED;
@@ -0,0 +1,9 @@
-- The claim now holds back a row while an older, unfinished row shares its destination and
-- ordering key. That check runs once per candidate row, so it needs an index or every claim scans
-- the backlog once per row it considers.
--
-- md5 of the key rather than the key: ordering_key is VARCHAR(1024), and a long multi-byte key
-- would exceed the btree entry limit and fail the business transaction that appends the row.
CREATE INDEX ix_messaging_outbox_unfinished_ordering_key
ON messaging_outbox (destination, md5(ordering_key), created_at)
WHERE ordering_key IS NOT NULL AND status IN ('PENDING', 'AMBIGUOUS', 'IN_FLIGHT');
@@ -0,0 +1,18 @@
-- Consumer inbox.
--
-- The composite primary key is the deduplication mechanism: reserving a message is an INSERT that
-- either succeeds or violates the key, inside the same transaction as the handler's side effect.
-- Two independent consumers of the same event each get their own row, so one cannot suppress the
-- other.
CREATE TABLE messaging_inbox
(
message_id UUID NOT NULL,
consumer_id VARCHAR(160) NOT NULL,
processed_at TIMESTAMPTZ NOT NULL,
CONSTRAINT pk_messaging_inbox PRIMARY KEY (message_id, consumer_id)
);
-- Retention sweeps read this. The window must outlive the broker's maximum redelivery delay:
-- pruning a row before its message can still be redelivered reopens the duplicate this table
-- exists to close.
CREATE INDEX ix_messaging_inbox_processed_at ON messaging_inbox (processed_at);
@@ -0,0 +1,98 @@
package dev.caskeleton.messaging.inbox;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.messaging.api.MessageId;
import dev.caskeleton.messaging.api.error.MessagingConfigurationException;
import java.time.Instant;
import javax.sql.DataSource;
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.springframework.transaction.support.TransactionSynchronizationManager;
/**
* What {@code reserve(...)} does when there is no transaction to join.
*
* <p>{@code IdempotentConsumer} calls this inside its transaction runner, and the implementation
* opened a raw connection that auto-commits. The reservation therefore survived a rollback of the
* side effect it was guarding: the message counts as processed, the work never happened, and
* redelivery is refused because the inbox row is already there.
*
* <p>Hermetic: the refusal has to happen before any connection is requested, and the data source
* below fails the test by being asked for one.
*/
class JdbcInboxTransactionRequirementTest {
/** A data source that fails the test by being used: the refusal must precede any connection. */
private final DataSource dataSource = new RefusingDataSource();
private final JdbcInboxRepository repository = new JdbcInboxRepository(dataSource);
@AfterEach
void clearTransactionState() {
TransactionSynchronizationManager.clear();
if (TransactionSynchronizationManager.hasResource(dataSource)) {
TransactionSynchronizationManager.unbindResource(dataSource);
}
}
@Test
@DisplayName("reserving outside a transaction is refused before a connection is opened")
void reservingOutsideATransactionIsRefused() {
assertThatThrownBy(() -> repository.reserve(MessageId.newId(), "order-projection", NOW))
.isInstanceOf(MessagingConfigurationException.class)
.hasMessageContaining("requires an active transaction");
}
@Test
@DisplayName("a read-only transaction is refused")
void aReadOnlyTransactionIsRefused() {
TransactionSynchronizationManager.setActualTransactionActive(true);
TransactionSynchronizationManager.setCurrentTransactionReadOnly(true);
assertThatThrownBy(() -> repository.reserve(MessageId.newId(), "order-projection", NOW))
.isInstanceOf(MessagingConfigurationException.class)
.hasMessageContaining("read-only");
}
@Test
@DisplayName("a transaction bound to another DataSource is refused")
void aTransactionOnAnotherDataSourceIsRefused() {
TransactionSynchronizationManager.setActualTransactionActive(true);
assertThatThrownBy(() -> repository.reserve(MessageId.newId(), "order-projection", NOW))
.as("two DataSources means two commits, which is the atomicity this exists to provide")
.isInstanceOf(MessagingConfigurationException.class)
.hasMessageContaining("bound to this DataSource");
}
@Test
@DisplayName("the refusal names a code an operator can search for")
void theRefusalNamesACode() {
assertThatThrownBy(() -> repository.reserve(MessageId.newId(), "order-projection", NOW))
.isInstanceOfSatisfying(
MessagingConfigurationException.class,
failure ->
assertThat(failure.failure().code()).isEqualTo("INBOX_TRANSACTION_REQUIRED"));
}
private static final Instant NOW = Instant.parse("2026-08-14T00:00:00Z");
/** Throws if anything asks it for a connection. */
private static final class RefusingDataSource
extends org.springframework.jdbc.datasource.AbstractDataSource {
@Override
public java.sql.Connection getConnection() {
throw new AssertionError(
"the refusal must happen before a connection is requested; opening one is the defect");
}
@Override
public java.sql.Connection getConnection(String username, String password) {
return getConnection();
}
}
}
@@ -0,0 +1,121 @@
package dev.caskeleton.messaging.outbox;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.messaging.api.ContentType;
import dev.caskeleton.messaging.api.MessageId;
import dev.caskeleton.messaging.api.MessageType;
import dev.caskeleton.messaging.api.SchemaVersion;
import dev.caskeleton.messaging.api.destination.DestinationName;
import dev.caskeleton.messaging.api.error.MessagingConfigurationException;
import dev.caskeleton.messaging.reliability.OutboxRecord;
import dev.caskeleton.messaging.reliability.OutboxStatus;
import java.time.Instant;
import java.util.Map;
import java.util.Optional;
import javax.sql.DataSource;
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.springframework.transaction.support.TransactionSynchronizationManager;
/**
* What {@code append(record)} does when there is no transaction to join.
*
* <p>The port says the append runs inside the caller's business transaction. The implementation
* called {@code dataSource.getConnection()}, which auto-commits on its own connection — so a
* business transaction that rolled back afterwards left the outbox row behind and the relay
* published an event for a change that never happened.
*
* <p>These are hermetic: the refusal happens before any connection is requested, which is also the
* property under test. The mock would fail the test by being touched at all.
*/
class JdbcOutboxTransactionRequirementTest {
/** A data source that fails the test by being used: the refusal must precede any connection. */
private final DataSource dataSource = new RefusingDataSource();
private final JdbcOutboxRepository repository = new JdbcOutboxRepository(dataSource);
@AfterEach
void clearTransactionState() {
TransactionSynchronizationManager.clear();
if (TransactionSynchronizationManager.hasResource(dataSource)) {
TransactionSynchronizationManager.unbindResource(dataSource);
}
}
@Test
@DisplayName("appending outside a transaction is refused before a connection is opened")
void appendingOutsideATransactionIsRefused() {
assertThatThrownBy(() -> repository.append(record()))
.isInstanceOf(MessagingConfigurationException.class)
.hasMessageContaining("requires an active transaction");
}
@Test
@DisplayName("a read-only transaction is refused")
void aReadOnlyTransactionIsRefused() {
TransactionSynchronizationManager.setActualTransactionActive(true);
TransactionSynchronizationManager.setCurrentTransactionReadOnly(true);
assertThatThrownBy(() -> repository.append(record()))
.isInstanceOf(MessagingConfigurationException.class)
.hasMessageContaining("read-only");
}
@Test
@DisplayName("a transaction bound to another DataSource is refused")
void aTransactionOnAnotherDataSourceIsRefused() {
TransactionSynchronizationManager.setActualTransactionActive(true);
assertThatThrownBy(() -> repository.append(record()))
.as("two DataSources means two commits, which is the atomicity this exists to provide")
.isInstanceOf(MessagingConfigurationException.class)
.hasMessageContaining("bound to this DataSource");
}
@Test
@DisplayName("the refusal names a code an operator can search for")
void theRefusalNamesACode() {
assertThatThrownBy(() -> repository.append(record()))
.isInstanceOfSatisfying(
MessagingConfigurationException.class,
failure ->
assertThat(failure.failure().code()).isEqualTo("OUTBOX_TRANSACTION_REQUIRED"));
}
private static OutboxRecord record() {
return new OutboxRecord(
MessageId.newId(),
new DestinationName("orders.events"),
new MessageType("order.placed"),
new SchemaVersion(1),
ContentType.JSON,
"{}".getBytes(java.nio.charset.StandardCharsets.UTF_8),
Map.of(),
dev.caskeleton.messaging.reliability.OutboxCanonicalMetadata.none(),
Instant.parse("2026-08-14T00:00:00Z"),
OutboxStatus.PENDING,
0,
Optional.empty(),
Optional.empty());
}
/** Throws if anything asks it for a connection. */
private static final class RefusingDataSource
extends org.springframework.jdbc.datasource.AbstractDataSource {
@Override
public java.sql.Connection getConnection() {
throw new AssertionError(
"the refusal must happen before a connection is requested; opening one is the defect");
}
@Override
public java.sql.Connection getConnection(String username, String password) {
return getConnection();
}
}
}