diff --git a/docs/messaging/outbox-inbox.md b/docs/messaging/outbox-inbox.md index bf68398..7167b1e 100644 --- a/docs/messaging/outbox-inbox.md +++ b/docs/messaging/outbox-inbox.md @@ -1,5 +1,10 @@ # Outbox · Inbox +> **이 템플릿 application의 소비 경로**: application의 `MessageHandler`와 inbox 부품(애플리케이션 +> DataSource 위 `JdbcInboxRepository`, `PlatformTransactionManager` 위 `TransactionRunner`)은 +> `adapter:inbound:messaging`(`src/adapter/inbound/messaging/README.md`)이 둔다. platform starter는 두 +> bean이 있을 때 `IdempotentConsumer`를 만들어 `INBOX_TRANSACTIONAL` destination의 handler를 감싼다. + ## 두 패턴이 각각 무엇을 해결하는가 | 패턴 | 해결하는 문제 | 해결하지 않는 문제 | diff --git a/messaging/messaging-kafka/build.gradle b/messaging/messaging-kafka/build.gradle index 00c9892..cfa3122 100644 --- a/messaging/messaging-kafka/build.gradle +++ b/messaging/messaging-kafka/build.gradle @@ -71,10 +71,10 @@ strictTestLanes { // floating tag would make a red run unattributable and a green one unrepeatable. // `-PmessagingKafkaImage=` overrides for a one-off run against another version. systemProperty 'messaging.kafka.image', - (project.findProperty('messagingKafkaImage') ?: 'apache/kafka:4.1.0').toString() + (project.findProperty('messagingKafkaImage') ?: testContainerImages['kafka']).toString() systemProperty 'messaging.toxiproxy.image', (project.findProperty('messagingToxiproxyImage') - ?: 'ghcr.io/shopify/toxiproxy:2.12.0').toString() + ?: testContainerImages['toxiproxy']).toString() systemProperty 'messaging.certification.manifest', project.layout.buildDirectory .file('messaging-certification/broker-certification-evidence.jsonl') diff --git a/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaAmbiguityChaosIT.java b/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaAmbiguityChaosIT.java index 21b4561..e278773 100644 --- a/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaAmbiguityChaosIT.java +++ b/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaAmbiguityChaosIT.java @@ -56,7 +56,9 @@ class KafkaAmbiguityChaosIT { private static final Instant NOW = Instant.parse("2026-08-10T09:15:00Z"); - @Container private static final KafkaContainer KAFKA = new KafkaContainer("apache/kafka:4.1.0"); + @Container + private static final KafkaContainer KAFKA = + new KafkaContainer(System.getProperty("ca.test.image.kafka")); static boolean dockerAvailable() { return DockerAvailability.isAvailable(); diff --git a/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaBrokerCertificationIT.java b/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaBrokerCertificationIT.java index 7a1dff7..beec17d 100644 --- a/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaBrokerCertificationIT.java +++ b/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaBrokerCertificationIT.java @@ -92,10 +92,11 @@ class KafkaBrokerCertificationIT { * latest} resolved to that morning". */ private static final String IMAGE = - System.getProperty("messaging.kafka.image", "apache/kafka:4.1.0"); + System.getProperty("messaging.kafka.image", System.getProperty("ca.test.image.kafka")); private static final String TOXIPROXY_IMAGE = - System.getProperty("messaging.toxiproxy.image", "ghcr.io/shopify/toxiproxy:2.12.0"); + System.getProperty( + "messaging.toxiproxy.image", System.getProperty("ca.test.image.toxiproxy")); /** The in-network listener the proxy forwards to. */ private static final int BROKER_PORT = 19092; diff --git a/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaBrokerIT.java b/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaBrokerIT.java index 89db8a6..ac3cec4 100644 --- a/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaBrokerIT.java +++ b/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaBrokerIT.java @@ -71,7 +71,9 @@ class KafkaBrokerIT { private static final String DEAD_LETTER_TOPIC = "order.events.v1.dlt"; private static final Instant NOW = Instant.parse("2026-08-10T09:15:00Z"); - @Container private static final KafkaContainer KAFKA = new KafkaContainer("apache/kafka:4.1.0"); + @Container + private static final KafkaContainer KAFKA = + new KafkaContainer(System.getProperty("ca.test.image.kafka")); private Producer producer; private Consumer consumer; diff --git a/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaContainerFixture.java b/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaContainerFixture.java index 9fb2e01..9d6b1a4 100644 --- a/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaContainerFixture.java +++ b/messaging/messaging-kafka/src/integrationTest/java/dev/caskeleton/messaging/kafka/KafkaContainerFixture.java @@ -35,7 +35,7 @@ import org.testcontainers.kafka.KafkaContainer; */ final class KafkaContainerFixture { - private static final String IMAGE = "apache/kafka:4.1.0"; + private static final String IMAGE = System.getProperty("ca.test.image.kafka"); private static KafkaContainer container; diff --git a/messaging/messaging-reliability-jdbc-postgresql/src/integrationTest/java/dev/caskeleton/messaging/inbox/InboxPostgresIT.java b/messaging/messaging-reliability-jdbc-postgresql/src/integrationTest/java/dev/caskeleton/messaging/inbox/InboxPostgresIT.java index 899707c..2ec95ce 100644 --- a/messaging/messaging-reliability-jdbc-postgresql/src/integrationTest/java/dev/caskeleton/messaging/inbox/InboxPostgresIT.java +++ b/messaging/messaging-reliability-jdbc-postgresql/src/integrationTest/java/dev/caskeleton/messaging/inbox/InboxPostgresIT.java @@ -45,7 +45,7 @@ class InboxPostgresIT { @SuppressWarnings("resource") @Container private static final PostgreSQLContainer POSTGRES = - new PostgreSQLContainer("postgres:16-alpine") + new PostgreSQLContainer(System.getProperty("ca.test.image.postgres-16")) .withDatabaseName("messaging") .withUsername("messaging") .withPassword("messaging"); diff --git a/messaging/messaging-reliability-jdbc-postgresql/src/integrationTest/java/dev/caskeleton/messaging/outbox/AdminOperationJournalPostgresIT.java b/messaging/messaging-reliability-jdbc-postgresql/src/integrationTest/java/dev/caskeleton/messaging/outbox/AdminOperationJournalPostgresIT.java index 7752598..5af7f49 100644 --- a/messaging/messaging-reliability-jdbc-postgresql/src/integrationTest/java/dev/caskeleton/messaging/outbox/AdminOperationJournalPostgresIT.java +++ b/messaging/messaging-reliability-jdbc-postgresql/src/integrationTest/java/dev/caskeleton/messaging/outbox/AdminOperationJournalPostgresIT.java @@ -50,7 +50,7 @@ class AdminOperationJournalPostgresIT { @SuppressWarnings("resource") @Container private static final PostgreSQLContainer POSTGRES = - new PostgreSQLContainer("postgres:16-alpine") + new PostgreSQLContainer(System.getProperty("ca.test.image.postgres-16")) .withDatabaseName("messaging") .withUsername("messaging") .withPassword("messaging"); diff --git a/messaging/messaging-reliability-jdbc-postgresql/src/integrationTest/java/dev/caskeleton/messaging/outbox/OutboxPostgresIT.java b/messaging/messaging-reliability-jdbc-postgresql/src/integrationTest/java/dev/caskeleton/messaging/outbox/OutboxPostgresIT.java index 16becff..388707d 100644 --- a/messaging/messaging-reliability-jdbc-postgresql/src/integrationTest/java/dev/caskeleton/messaging/outbox/OutboxPostgresIT.java +++ b/messaging/messaging-reliability-jdbc-postgresql/src/integrationTest/java/dev/caskeleton/messaging/outbox/OutboxPostgresIT.java @@ -51,7 +51,7 @@ class OutboxPostgresIT { @SuppressWarnings("resource") @Container private static final PostgreSQLContainer POSTGRES = - new PostgreSQLContainer("postgres:16-alpine") + new PostgreSQLContainer(System.getProperty("ca.test.image.postgres-16")) .withDatabaseName("messaging") .withUsername("messaging") .withPassword("messaging"); diff --git a/messaging/messaging-spring-boot-starter/src/integrationTest/java/dev/caskeleton/messaging/autoconfigure/MessagingKafkaConsumeQualificationTest.java b/messaging/messaging-spring-boot-starter/src/integrationTest/java/dev/caskeleton/messaging/autoconfigure/MessagingKafkaConsumeQualificationTest.java index 7083bc6..13ad8fc 100644 --- a/messaging/messaging-spring-boot-starter/src/integrationTest/java/dev/caskeleton/messaging/autoconfigure/MessagingKafkaConsumeQualificationTest.java +++ b/messaging/messaging-spring-boot-starter/src/integrationTest/java/dev/caskeleton/messaging/autoconfigure/MessagingKafkaConsumeQualificationTest.java @@ -97,13 +97,14 @@ class MessagingKafkaConsumeQualificationTest { private static final MessageType CREATED = new MessageType("order.created"); - @Container static final KafkaContainer KAFKA = new KafkaContainer("apache/kafka:4.1.0"); + @Container + static final KafkaContainer KAFKA = new KafkaContainer(System.getProperty("ca.test.image.kafka")); // @Container: the Testcontainers JUnit extension owns this lifecycle. @SuppressWarnings("resource") @Container static final PostgreSQLContainer POSTGRES = - new PostgreSQLContainer("postgres:16-alpine") + new PostgreSQLContainer(System.getProperty("ca.test.image.postgres-16")) .withDatabaseName("messaging") .withUsername("messaging") .withPassword("messaging"); diff --git a/messaging/messaging-spring-boot-starter/src/integrationTest/java/dev/caskeleton/messaging/autoconfigure/MessagingLiveRoundTripQualificationTest.java b/messaging/messaging-spring-boot-starter/src/integrationTest/java/dev/caskeleton/messaging/autoconfigure/MessagingLiveRoundTripQualificationTest.java index 42c1d15..a4d9604 100644 --- a/messaging/messaging-spring-boot-starter/src/integrationTest/java/dev/caskeleton/messaging/autoconfigure/MessagingLiveRoundTripQualificationTest.java +++ b/messaging/messaging-spring-boot-starter/src/integrationTest/java/dev/caskeleton/messaging/autoconfigure/MessagingLiveRoundTripQualificationTest.java @@ -63,7 +63,8 @@ class MessagingLiveRoundTripQualificationTest { // membership against 3.8.0 proved the membership on a broker two minors below the one the matrix // calls certified, so the one test that decides whether the starter may reach a deployment's // classpath was the only one not run against what a deployment gets. - @Container static final KafkaContainer KAFKA = new KafkaContainer("apache/kafka:4.1.0"); + @Container + static final KafkaContainer KAFKA = new KafkaContainer(System.getProperty("ca.test.image.kafka")); static boolean dockerAvailable() { return DockerClientFactory.instance().isDockerAvailable(); diff --git a/messaging/messaging-spring-boot-starter/src/integrationTest/java/dev/caskeleton/messaging/autoconfigure/MessagingSecuredBrokerQualificationTest.java b/messaging/messaging-spring-boot-starter/src/integrationTest/java/dev/caskeleton/messaging/autoconfigure/MessagingSecuredBrokerQualificationTest.java index 5e823a3..8a081cc 100644 --- a/messaging/messaging-spring-boot-starter/src/integrationTest/java/dev/caskeleton/messaging/autoconfigure/MessagingSecuredBrokerQualificationTest.java +++ b/messaging/messaging-spring-boot-starter/src/integrationTest/java/dev/caskeleton/messaging/autoconfigure/MessagingSecuredBrokerQualificationTest.java @@ -43,7 +43,7 @@ import org.testcontainers.utility.MountableFile; @EnabledIf(value = "dockerAvailable", disabledReason = "Docker not available for the live broker") class MessagingSecuredBrokerQualificationTest { - private static final String IMAGE = "apache/kafka:4.1.0"; + private static final String IMAGE = System.getProperty("ca.test.image.kafka"); private static final String BROKER_USER = "svc-orders"; diff --git a/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingReliabilityAutoConfiguration.java b/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingReliabilityAutoConfiguration.java index f6e096a..7696cde 100644 --- a/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingReliabilityAutoConfiguration.java +++ b/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingReliabilityAutoConfiguration.java @@ -1,6 +1,7 @@ package dev.caskeleton.messaging.autoconfigure; import dev.caskeleton.messaging.api.publish.MessagePublisher; +import dev.caskeleton.messaging.inbox.IdempotentConsumer; import dev.caskeleton.messaging.inbox.InboxCleanupJob; import dev.caskeleton.messaging.inbox.InboxRetentionPolicy; import dev.caskeleton.messaging.outbox.OutboxCleanupJob; @@ -180,6 +181,27 @@ public class MessagingReliabilityAutoConfiguration { return new InboxRetentionPolicy(InboxRetentionPolicy.DEFAULT_RETENTION, Duration.ofDays(1)); } + /** + * Returns the inbox runner that {@code INBOX_TRANSACTIONAL} destinations wrap their handlers in + * ({@link MessagingConsumeConfiguration}). + * + *

Assembled from the two parts the platform cannot supply itself, like every bean here: the + * application's inbox repository and the runner that opens the application's transaction, so the + * reservation and the handler's side effect commit or roll back together. Without both, an {@code + * INBOX_TRANSACTIONAL} destination still refuses to start. + * + * @param inbox the application's inbox repository + * @param transactions runs work in the application's transaction + * @return the idempotent consumer + */ + @Bean + @ConditionalOnBean({InboxRepository.class, IdempotentConsumer.TransactionRunner.class}) + @ConditionalOnMissingBean + public IdempotentConsumer idempotentConsumer( + InboxRepository inbox, IdempotentConsumer.TransactionRunner transactions) { + return new IdempotentConsumer(inbox, transactions); + } + /** * Returns the inbox cleanup job. * diff --git a/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingShutdownLifecycle.java b/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingShutdownLifecycle.java index 0229f13..7efaa47 100644 --- a/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingShutdownLifecycle.java +++ b/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingShutdownLifecycle.java @@ -30,6 +30,13 @@ import org.springframework.context.SmartLifecycle; public final class MessagingShutdownLifecycle implements SmartLifecycle { /** How often the drain is re-checked. Short enough that a fast drain is not padded. */ + /** + * The phase this drain stops in: {@link #getPhase()}. Public so a relay outside the platform — + * the application's own outbox relay, which may not name this type in production code — can be + * held above it by a test that does name it. + */ + public static final int PHASE = Integer.MAX_VALUE - 1024; + private static final Duration POLL = Duration.ofMillis(50); private final MessagingAdmissionController admission; @@ -111,14 +118,18 @@ public final class MessagingShutdownLifecycle implements SmartLifecycle { * *

{@code SmartLifecycle} stops in descending phase order. A phase above the default puts this * drain ahead of the transports it is draining, because closing a connection first would strand - * the settlements the drain exists to flush. It sits below the outbox relay's phase for the + * the settlements the drain exists to flush. It sits below the outbox relays' phase for the * mirror-image reason: refusing admission while a relay pass is mid-publish turns that pass's - * rows ambiguous, which is the uncertainty the drain exists to avoid. + * rows into refusals. Two relays stand above it: the platform's own ({@code + * MessagingOutboxRelayLifecycle}, built only when a platform outbox repository exists) and the + * application's ({@code composition:outbox-relay} {@code OutboxRelayScheduler}, phase {@code + * Integer.MAX_VALUE}), which finishes the publish it is in and releases its other claims before + * this phase runs. * - * @return the lifecycle phase + * @return the lifecycle phase, {@link #PHASE} */ @Override public int getPhase() { - return Integer.MAX_VALUE - 1024; + return PHASE; } } diff --git a/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingInboxAssemblyTest.java b/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingInboxAssemblyTest.java new file mode 100644 index 0000000..1bc1271 --- /dev/null +++ b/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingInboxAssemblyTest.java @@ -0,0 +1,68 @@ +package dev.caskeleton.messaging.autoconfigure; + +import static org.assertj.core.api.Assertions.assertThat; + +import dev.caskeleton.messaging.api.MessageId; +import dev.caskeleton.messaging.inbox.IdempotentConsumer; +import dev.caskeleton.messaging.reliability.InboxRepository; +import java.time.Instant; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.springframework.boot.test.context.runner.ApplicationContextRunner; + +/** + * The platform assembles its inbox runner from the two parts only the application can supply + * (review 06-08): nothing assembled it before, so an INBOX_TRANSACTIONAL destination could only + * refuse to start. + */ +class MessagingInboxAssemblyTest { + + private final ApplicationContextRunner runner = + new ApplicationContextRunner() + .withUserConfiguration(MessagingReliabilityAutoConfiguration.class); + + @Test + @DisplayName("애플리케이션이 inbox 저장소와 트랜잭션 runner를 주면 platform이 IdempotentConsumer를 만든다") + void theApplicationsInboxPartsAssembleTheIdempotentConsumer() { + // when & then + runner + .withBean(InboxRepository.class, NoInbox::new) + .withBean(IdempotentConsumer.TransactionRunner.class, () -> Runner.DIRECT) + .run(context -> assertThat(context).hasSingleBean(IdempotentConsumer.class)); + } + + @Test + @DisplayName("트랜잭션 runner가 없으면 IdempotentConsumer를 만들지 않는다") + void withoutTheApplicationsTransactionNoIdempotentConsumerIsAssembled() { + // when & then + runner + .withBean(InboxRepository.class, NoInbox::new) + .run(context -> assertThat(context).doesNotHaveBean(IdempotentConsumer.class)); + } + + private enum Runner implements IdempotentConsumer.TransactionRunner { + DIRECT; + + @Override + public T inTransaction(java.util.function.Supplier work) { + return work.get(); + } + } + + private static final class NoInbox implements InboxRepository { + @Override + public boolean reserve(MessageId messageId, String consumerId, Instant now) { + return true; + } + + @Override + public boolean isProcessed(MessageId messageId, String consumerId) { + return false; + } + + @Override + public int purgeProcessedBefore(Instant processedBefore, int limit) { + return 0; + } + } +} diff --git a/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/contract/MessagingPublicSurfaceContractTest.java b/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/contract/MessagingPublicSurfaceContractTest.java index 00756f7..922d939 100644 --- a/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/contract/MessagingPublicSurfaceContractTest.java +++ b/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/contract/MessagingPublicSurfaceContractTest.java @@ -2,6 +2,7 @@ package dev.caskeleton.bootstrap.contract.messaging; import static org.assertj.core.api.Assertions.assertThat; +import dev.caskeleton.bootstrap.contract.support.RepositoryContractResources; import java.io.IOException; import java.io.UncheckedIOException; import java.nio.file.Files; @@ -16,6 +17,7 @@ import java.util.regex.Matcher; import java.util.regex.Pattern; import java.util.stream.Stream; import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Tag; import org.junit.jupiter.api.Test; /** @@ -41,6 +43,7 @@ import org.junit.jupiter.api.Test; * composition boundary, where the container constructs the types rather than an adopter naming * them, and that boundary is where the family policy already confines them. */ +@Tag("repository-contract") class MessagingPublicSurfaceContractTest { /** @@ -375,14 +378,9 @@ class MessagingPublicSurfaceContractTest { } private static Path repositoryRoot() { - Path candidate = Path.of("").toAbsolutePath(); - while (candidate != null - && !Files.isRegularFile(candidate.resolve("src/config/architecture/modules.json"))) { - candidate = candidate.getParent(); - } - if (candidate == null) { - throw new IllegalStateException("the repository root is not above the working directory"); - } - return candidate; + // Gradle hands the root only to the lanes that declare the repository files as inputs; the + // plain `test` lane gets none, so a test that reads the repository without a lane tag fails + // here instead of going stale behind an up-to-date check (review 2026-11-01 08-03). + return RepositoryContractResources.fromSystemProperty().repositoryRoot(); } }