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:
co-authored by
Claude Opus 5.5
parent
b5e3c03777
commit
6397f52dc8
+206
@@ -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);
|
||||
}
|
||||
}
|
||||
}
|
||||
+209
@@ -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);
|
||||
}
|
||||
}
|
||||
}
|
||||
+642
@@ -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));
|
||||
}
|
||||
}
|
||||
+170
@@ -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);
|
||||
}
|
||||
}
|
||||
}
|
||||
+326
@@ -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;
|
||||
}
|
||||
}
|
||||
+527
@@ -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;
|
||||
}
|
||||
}
|
||||
+41
@@ -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';
|
||||
+39
@@ -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');
|
||||
+37
@@ -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';
|
||||
+66
@@ -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;
|
||||
+9
@@ -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');
|
||||
+18
@@ -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);
|
||||
+98
@@ -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();
|
||||
}
|
||||
}
|
||||
}
|
||||
+121
@@ -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();
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user