From 8c2a88a2fe6e159982afc4f65caba493d1f50690 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Tue, 3 Nov 2026 19:52:06 +0900 Subject: [PATCH 1/6] =?UTF-8?q?fix!:=20=EC=84=B1=EC=88=99=EB=8F=84=20?= =?UTF-8?q?=EB=A6=AC=EB=B7=B0=EC=9D=98=20High=C2=B7P1=20=EA=B2=B0=ED=95=A8?= =?UTF-8?q?=2019=EA=B1=B4=EC=9D=84=20=EA=B3=A0=EC=B9=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 2026-11-01 성숙도 리뷰에서 High 21건·P1 25건이 나왔다. 결과를 모르는 일을 "확실함"으로 기록했다(발송 중 죽은 알림 재발송, 커밋 중 끊긴 쓰기를 재시도 가능으로 응답, 재시도 가능한 거부를 DEAD로). 중복을 DB가 아니라 코드 순서로 막았다(정산 job, 포스터 제목). 짝 프론트와 wire 계약이 달랐고(처리 중 409, Envelope null), JWT audience 검증이 기본으로 꺼져 있었고, 트레이스가 나가지 않았고, CI가 strict lane 14개를 한 번도 돌리지 않았다. 방법: 발견마다 실패하는 테스트를 먼저 쓰고 고쳤다. 주요 선택: - 알림 attempt는 처음부터 "시작 여부 모름"으로 쓴다(호출 직전 갱신은 쓰기가 하나 늘어 버림). - 정산 job claim은 lease·fence를 갱신하는 UPDATE 한 문장(처리 전체를 트랜잭션으로 감싸는 안은 외부 호출 동안 잠금을 잡아 버림). - 커밋 단계 연결 끊김은 DB_COMPLETION_UNKNOWN(재시도 불가). - 처리 중 409는 retryable=true + Retry-After: 2, Envelope null 필드는 web Jackson mixin으로 생략(shared-contract는 stdlib only). - 트레이싱은 자체 Tracer를 지우고 Boot 4 tracing·OTLP로. - strict lane을 단계에 연결하고 verifyStrictLaneStages가 고아를 막는다. 발견별 RED·GREEN·버린 대안은 리뷰 README 13절 표에 있다. 위험·한계: JWT 모드는 APP_SECURITY_JWT_AUDIENCE가 없으면 기동하지 않는다. 짝 프론트는 409 retryable과 Envelope 키 규칙을 맞춰야 한다. 이 커밋 시점에는 MinIO 공식 이미지가 사라져 MinIO 2 lane이 실패한다 (다음 커밋에서 대체 이미지로 해결). 검증: ci 통과. mainCheck·integrationCheck는 MinIO 2 lane만 실패(이미지 pull 거부). -p optional-platforms ci integrationCheck, performanceCheck, releaseCheck(-PgitRevision) 통과. Refs: docs/reviews/2026-11-01-maturity-review/README.md 2·13절 BREAKING CHANGE: JWT 모드에서 APP_SECURITY_JWT_AUDIENCE가 필수가 되고 role은 audience client와 realm 것만 읽는다. IDEMPOTENT_IN_FLIGHT가 retryable=true, Retry-After: 2로 바뀌고 Envelope는 null 필드를 보내지 않는다. --- docs/messaging/delivery-guarantees.md | 7 +- .../kafka/KafkaMessagingTransport.java | 11 ++- .../kafka/KafkaPublishFailureClassifier.java | 24 ++++++- .../kafka/KafkaMessagingTransportTest.java | 43 ++++++++++++ .../KafkaPublishFailureClassifierTest.java | 69 +++++++++++++++++++ .../runtime/DefaultMessagePublisher.java | 12 +++- .../runtime/DefaultMessagePublisherTest.java | 31 +++++++++ 7 files changed, 191 insertions(+), 6 deletions(-) create mode 100644 messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaMessagingTransportTest.java create mode 100644 messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaPublishFailureClassifierTest.java diff --git a/docs/messaging/delivery-guarantees.md b/docs/messaging/delivery-guarantees.md index 518aa3e..d980932 100644 --- a/docs/messaging/delivery-guarantees.md +++ b/docs/messaging/delivery-guarantees.md @@ -19,7 +19,12 @@ public enum PublishCompletion { CONFIRMED, REJECTED, AMBIGUOUS } ``` `REJECTED`와 `AMBIGUOUS`를 하나의 "실패"로 합치면 중복 주문이 만들어진다. -전자는 broker가 저장하지 않았음이 **확정**되어 포기해도 안전하고, 후자는 그렇지 않다. +전자는 broker가 저장하지 않았음이 **확정**되어 중복 걱정 없이 다시 보내거나 포기할 수 있고, 후자는 그렇지 않다. + +`REJECTED`가 곧 "포기해도 된다"는 뜻은 아니다. 거부 이유가 그 순간에 속하면(종료 중 +`SHUTTING_DOWN`, permit 대기 초과, `PUBLISH_RUNTIME_UNAVAILABLE`, `KAFKA_TRANSPORT_CLOSED`, Kafka +인증·인가 실패) `failure().retryable()`이 true이고, 호출자는 같은 메시지를 나중에 다시 보내야 한다. +포기해도 되는 것은 `retryable=false`인 거부뿐이다. | 상황 | 결과 | |---|---| diff --git a/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaMessagingTransport.java b/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaMessagingTransport.java index e80cff4..ce84b54 100644 --- a/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaMessagingTransport.java +++ b/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaMessagingTransport.java @@ -119,7 +119,16 @@ public final class KafkaMessagingTransport implements MessagingTransport { Objects.requireNonNull(request, "request must not be null"); if (closed.get()) { - return completed(rejectedLocally("KAFKA_TRANSPORT_CLOSED", "the transport is shutting down")); + // Not the message's fault: the next instance, or this one after a restart, will take it. A + // caller that trusts the retryable flag must not park it. + return completed( + new TransportPublishResult( + PublishResult.rejected( + Duration.ZERO, + FailureDescriptor.of( + FailureCategory.TRANSIENT_INFRASTRUCTURE, + "KAFKA_TRANSPORT_CLOSED", + "the transport is shutting down")))); } int size = request.envelope().payload().size(); int limit = request.profile().payload().maxBytes(); diff --git a/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaPublishFailureClassifier.java b/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaPublishFailureClassifier.java index 3436871..0eea955 100644 --- a/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaPublishFailureClassifier.java +++ b/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaPublishFailureClassifier.java @@ -19,8 +19,10 @@ import org.apache.kafka.common.errors.UnsupportedVersionException; *

The split is between failures that prove the record was not stored and failures that prove * nothing. Serialization, an invalid topic, authentication, authorization, fencing, and an * over-large record are all rejections: the broker never took the record, so abandoning the attempt - * is safe. Everything else — a delivery timeout above all — is ambiguous, because the record may - * already be replicated and only the acknowledgement was lost. + * is safe. Of those, authentication and authorization are marked retryable, because they clear on + * their own once a credential or an ACL is in place. Everything else — a delivery timeout above all + * — is ambiguous, because the record may already be replicated and only the acknowledgement was + * lost. * *

The default is deliberately ambiguous rather than rejected. Guessing "rejected" on an unknown * error is what turns one lost confirmation into two orders. @@ -37,7 +39,8 @@ public final class KafkaPublishFailureClassifier { public PublishResult classify(Throwable error, Duration elapsed) { Throwable cause = unwrap(error); if (isDefinitiveRejection(cause)) { - return PublishResult.rejected(elapsed, descriptor(cause, rejectionCategory(cause), false)); + return PublishResult.rejected( + elapsed, descriptor(cause, rejectionCategory(cause), mayPassOnRetry(cause))); } return PublishResult.ambiguous(elapsed, descriptor(cause, FailureCategory.AMBIGUOUS, false)); } @@ -58,6 +61,21 @@ public final class KafkaPublishFailureClassifier { || cause instanceof UnsupportedVersionException; } + /** + * Reports whether a definitive rejection may pass if the same record is sent again later. + * + *

Authentication and authorization prove the broker did not store the record, but not that it + * will refuse it again: a credential being rotated, or an ACL deployed after the application, + * fails every publish this way for a few minutes and then stops. Marked not retryable, a + * publisher that trusts the flag — the application's outbox relay does — parks every record sent + * in those minutes. A credential that is simply wrong is retried too, and the outbox then holds + * its rows FAILED with an alert every retry — recoverable once the credential is fixed, where + * DEAD rows needed a manual reset each. + */ + private static boolean mayPassOnRetry(Throwable cause) { + return cause instanceof AuthenticationException || cause instanceof AuthorizationException; + } + private static FailureCategory rejectionCategory(Throwable cause) { if (cause instanceof AuthenticationException) { return FailureCategory.AUTHENTICATION; diff --git a/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaMessagingTransportTest.java b/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaMessagingTransportTest.java new file mode 100644 index 0000000..d50ce60 --- /dev/null +++ b/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaMessagingTransportTest.java @@ -0,0 +1,43 @@ +package dev.caskeleton.messaging.kafka; + +import static org.assertj.core.api.Assertions.assertThat; + +import dev.caskeleton.messaging.api.error.FailureDescriptor; +import dev.caskeleton.messaging.api.publish.PublishCompletion; +import dev.caskeleton.messaging.api.publish.PublishOptions; +import dev.caskeleton.messaging.api.publish.PublishResult; +import dev.caskeleton.messaging.transport.TransportPublishRequest; +import org.apache.kafka.clients.producer.MockProducer; +import org.apache.kafka.clients.producer.Partitioner; +import org.apache.kafka.common.serialization.ByteArraySerializer; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; + +/** What a closed Kafka transport answers a publish that arrives during shutdown. */ +class KafkaMessagingTransportTest { + + @Test + @DisplayName("닫힌 transport의 거부는 다음 인스턴스가 받을 수 있으므로 다시 시도할 수 있다고 표시한다") + void aPublishToAClosedTransportIsARefusalThatMayBeRetried() { + // given: the transport closed while a relay cycle was still publishing + KafkaMessagingTransport transport = + new KafkaMessagingTransport( + "kafka-primary", + 1, + new MockProducer<>( + false, (Partitioner) null, new ByteArraySerializer(), new ByteArraySerializer())); + transport.close(); + TransportPublishRequest request = + new TransportPublishRequest( + KafkaContractHarness.profile(), + KafkaFixtures.orderCreatedEnvelope(), + PublishOptions.defaults()); + + // when + PublishResult result = transport.publish(request).toCompletableFuture().join().result(); + + // then + assertThat(result.completion()).isEqualTo(PublishCompletion.REJECTED); + assertThat(result.failure()).get().extracting(FailureDescriptor::retryable).isEqualTo(true); + } +} diff --git a/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaPublishFailureClassifierTest.java b/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaPublishFailureClassifierTest.java new file mode 100644 index 0000000..cdbae5a --- /dev/null +++ b/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaPublishFailureClassifierTest.java @@ -0,0 +1,69 @@ +package dev.caskeleton.messaging.kafka; + +import static org.assertj.core.api.Assertions.assertThat; + +import dev.caskeleton.messaging.api.error.FailureDescriptor; +import dev.caskeleton.messaging.api.publish.PublishCompletion; +import dev.caskeleton.messaging.api.publish.PublishResult; +import java.time.Duration; +import org.apache.kafka.common.errors.AuthenticationException; +import org.apache.kafka.common.errors.AuthorizationException; +import org.apache.kafka.common.errors.InvalidTopicException; +import org.apache.kafka.common.errors.TopicAuthorizationException; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; + +/** + * Which producer failures a publisher may retry. + * + *

Authentication and authorization failures prove the broker did not store the record, so they + * are rejections. They are not proof the record will be refused again: a credential being rotated + * or an ACL deployed after the application fails this way for a few minutes and then stops. + */ +class KafkaPublishFailureClassifierTest { + + private final KafkaPublishFailureClassifier classifier = new KafkaPublishFailureClassifier(); + + @Test + @DisplayName("인증 실패는 저장되지 않은 거부지만 다시 시도할 수 있다고 표시한다") + void anAuthenticationFailureIsARejectionThatMayBeRetried() { + // given + AuthenticationException rotatingCredential = + new AuthenticationException("SASL authentication failed"); + + // when + PublishResult result = classifier.classify(rotatingCredential, Duration.ZERO); + + // then + assertThat(result.completion()).isEqualTo(PublishCompletion.REJECTED); + assertThat(result.failure()).get().extracting(FailureDescriptor::retryable).isEqualTo(true); + } + + @Test + @DisplayName("인가 실패는 저장되지 않은 거부지만 다시 시도할 수 있다고 표시한다") + void anAuthorizationFailureIsARejectionThatMayBeRetried() { + // given + AuthorizationException aclNotYetDeployed = new TopicAuthorizationException("orders"); + + // when + PublishResult result = classifier.classify(aclNotYetDeployed, Duration.ZERO); + + // then + assertThat(result.completion()).isEqualTo(PublishCompletion.REJECTED); + assertThat(result.failure()).get().extracting(FailureDescriptor::retryable).isEqualTo(true); + } + + @Test + @DisplayName("존재하지 않는 topic은 다시 시도해도 같으므로 다시 시도할 수 없다고 표시한다") + void anInvalidTopicIsARejectionThatMayNotBeRetried() { + // given + InvalidTopicException noSuchTopic = new InvalidTopicException("no such topic"); + + // when + PublishResult result = classifier.classify(noSuchTopic, Duration.ZERO); + + // then + assertThat(result.completion()).isEqualTo(PublishCompletion.REJECTED); + assertThat(result.failure()).get().extracting(FailureDescriptor::retryable).isEqualTo(false); + } +} diff --git a/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisher.java b/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisher.java index 0f6d9e2..a51f9fe 100644 --- a/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisher.java +++ b/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisher.java @@ -263,7 +263,17 @@ public final class DefaultMessagePublisher implements MessagePublisher, EncodedM lease.close(); } admission.complete(destination.name().value()); - return rejected("PUBLISH_RUNTIME_UNAVAILABLE", sanitized(beforeTheSend), startedAt); + // No runtime to send through — the registry closed during shutdown, or none is installed + // yet. Nothing about the message was wrong, so the refusal is marked retryable: a caller that + // trusts the flag, as the application's outbox relay does, retries it instead of parking it. + return refused( + new FailureDescriptor( + FailureCategory.TRANSIENT_INFRASTRUCTURE, + "PUBLISH_RUNTIME_UNAVAILABLE", + true, + sanitized(beforeTheSend), + Optional.empty()), + startedAt); } } diff --git a/messaging/messaging-runtime-core/src/test/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisherTest.java b/messaging/messaging-runtime-core/src/test/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisherTest.java index 4ac4854..5a9b750 100644 --- a/messaging/messaging-runtime-core/src/test/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisherTest.java +++ b/messaging/messaging-runtime-core/src/test/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisherTest.java @@ -420,6 +420,37 @@ class DefaultMessagePublisherTest { assertThat(admission.inFlight()).isZero(); } + @Test + @DisplayName("runtime이 없어서 생긴 거부는 다시 시도할 수 있다고 표시한다") + void aRefusalForAnUnavailableRuntimeMayBeRetried() { + // given: the runtime registry closed during shutdown, before this publish acquired it + DefaultMessagePublisher publisher = + new DefaultMessagePublisher( + registry(), + allowOrders(), + new SingleCodecRegistry(), + admission, + new FailingRuntimeRegistry(), + transport); + + // when + PublishResult result = + publisher + .publish( + new MessageDestination<>(ORDERS, new MessageType("order.created"), String.class), + envelope(), + PublishOptions.defaults()) + .toCompletableFuture() + .join(); + + // then: nothing about the message was wrong, so a later attempt may succeed + assertThat(result.completion()).isEqualTo(PublishCompletion.REJECTED); + assertThat(result.failure()) + .get() + .extracting(FailureDescriptor::code, FailureDescriptor::retryable) + .containsExactly("PUBLISH_RUNTIME_UNAVAILABLE", true); + } + @Test @DisplayName("an unregistered destination names itself") void anUnregisteredDestinationNamesItself() { From 899f1f920c5524a80c8836aeceb5495801072ba8 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Tue, 3 Nov 2026 19:52:06 +0900 Subject: [PATCH 2/6] =?UTF-8?q?feat!:=20=EB=82=A8=EC=9D=80=20=EB=A6=AC?= =?UTF-8?q?=EB=B7=B0=20=EB=B0=9C=EA=B2=AC=EC=9D=84=20=EA=B3=A0=EC=B9=98?= =?UTF-8?q?=EA=B3=A0=20=EA=B0=9C=EB=B0=9C=20=EB=A7=A4=EB=89=B4=EC=96=BC?= =?UTF-8?q?=EA=B3=BC=20=EA=B8=B0=EB=8A=A5=20=EC=83=9D=EC=84=B1=20=EB=AA=85?= =?UTF-8?q?=EB=A0=B9=EC=9D=84=20=EB=8D=94=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: High·P1을 고친 뒤에도 P2·P3 약 90건이 남았다. 연결·구독·메시지 크기 상한이 없는 전송(WebSocket·gRPC·GraphQL deadline), 낙관적 충돌의 500, upsert 경쟁, Mongo 무제한 timeout, 샘플 목록 N+1, 갈라진 복사본 (TenantId 3벌, 이벤트 ID 문법 5곳, SQLState 표 2벌), 문서를 읽는 PR 테스트와 캐시를 막는 lane 설정 등이다. 새 기능을 어디에 어떤 순서로 만드는지 알려 주는 문서와 도구가 없었다. MinIO 공식 이미지가 사라져 객체 저장소 lane이 돌지 않았다. 방법: 영역별 묶음으로 실패 테스트를 먼저 쓰고 고쳤다. 고치는 중에 찾은 결함도 함께 고쳤다(durable operation id가 UUIDv4라 이벤트가 전부 DEAD, S3 어댑터 생성·작은 chunk 읽기 실패, Redis 조건부 기록의 EVALSHA 권한). MinIO는 pgsty/minio를 digest로 고정했다(Chainguard는 태그·실행 사용자· mc 이미지 문제로 버림). docs/manual/에 작업 순서와 판단 지점을 쓰고, scripts/new-feature.sh가 5개 leaf에 뼈대를 만든다. 생성→빌드→통과 왕복을 verifyFeatureScaffold가 mainCheck에서 본다. 묶음별 결과와 결정은 리뷰 README 14절에 있다. 위험·한계: 파생 서비스 동작이 바뀐다. JDBC batch 50 기본, 운영 jar에서 H2 제거, 트랜잭션 30초 제한, 격리 수준을 Hikari에서 고정, gRPC· WebSocket·GraphQL 새 한도, correlation ID 규칙 밖이면 서버가 교체, 샘플 키 오류 코드 IDEMPOTENCY_KEY_INVALID. 새 leaf 두 개 (composition:durable-operation, adapter:inbound:messaging)와 새 마이그레이션(postgresql V20·V21, notification V11·V12, sample V8_1, grpc-ledger V002)이 생긴다. V21 유일 인덱스는 기존 중복이 있으면 실패한다(runbook에 확인 쿼리). 검증: ci, mainCheck(생성 명령 왕복 포함), integrationCheck(MinIO 포함 전 컨테이너 lane), -p optional-platforms ci integrationCheck 통과. Refs: docs/reviews/2026-11-01-maturity-review/README.md 14절 BREAKING CHANGE: JDBC batch 기본 켜짐, H2 운영 의존 제거, 트랜잭션 기본 제한 30초, gRPC·WebSocket·GraphQL 서버 한도 기본값 추가, 샘플 Idempotency-Key 오류 코드 변경. --- docs/messaging/outbox-inbox.md | 5 ++ messaging/messaging-kafka/build.gradle | 4 +- .../kafka/KafkaAmbiguityChaosIT.java | 4 +- .../kafka/KafkaBrokerCertificationIT.java | 5 +- .../messaging/kafka/KafkaBrokerIT.java | 4 +- .../kafka/KafkaContainerFixture.java | 2 +- .../messaging/inbox/InboxPostgresIT.java | 2 +- .../AdminOperationJournalPostgresIT.java | 2 +- .../messaging/outbox/OutboxPostgresIT.java | 2 +- ...essagingKafkaConsumeQualificationTest.java | 5 +- ...ssagingLiveRoundTripQualificationTest.java | 3 +- ...ssagingSecuredBrokerQualificationTest.java | 2 +- ...MessagingReliabilityAutoConfiguration.java | 22 ++++++ .../MessagingShutdownLifecycle.java | 19 ++++-- .../MessagingInboxAssemblyTest.java | 68 +++++++++++++++++++ .../MessagingPublicSurfaceContractTest.java | 16 ++--- 16 files changed, 138 insertions(+), 27 deletions(-) create mode 100644 messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingInboxAssemblyTest.java 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(); } } From 8e903dce31b66807cb6101c9cf7b604706a9ef15 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Tue, 3 Nov 2026 19:52:06 +0900 Subject: [PATCH 3/6] =?UTF-8?q?fix!:=20=EB=82=A8=EC=9D=80=20=EB=A6=AC?= =?UTF-8?q?=EB=B7=B0=20=ED=95=AD=EB=AA=A9=EA=B3=BC=20=ED=95=A9=EC=B9=9C=20?= =?UTF-8?q?=EB=92=A4=20=EB=93=9C=EB=9F=AC=EB=82=9C=20=EA=B2=B0=ED=95=A8?= =?UTF-8?q?=EC=9D=84=20=EA=B3=A0=EC=B9=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 앞 커밋 뒤에도 알림·파일 서버 묶음이 합쳐지지 않았고, 포트 다수에 fake와 실제 구현이 함께 통과하는 공유 계약이 없었고, SpotBugs가 신뢰도 HIGH만 봤고, application-core에 관계없는 클래스 묶음 패키지(outbound)가 있었다. 묶음을 합치자 lane·검사가 새로 드러낸 결함도 있었다(JpaOutbox Store가 읽기 전용 트랜잭션에서 이벤트를 조용히 잃음, gRPC admission controller가 public synchronized라 외부 lock에 막힘, 소비자 decode 타입 등록 경로 없음, compose Redis 익명 접근, local-fileserver lane DB 없음). 방법: 리뷰 README 15절에 남은 결정을 모두 적고 그대로 고쳤다. 트랜잭션· 멱등성·발행·notification 포트에 testFixtures 계약 키트를 두고 fake와 PG·Redis 구현이 상속한다(fake 변이로 계약이 잡는지 확인). SpotBugs는 MEDIUM으로 내리고 진짜 결함은 고치고 오탐은 위치·패턴별 이유를 단 제외로 처리했다. 업무 기능 패키지 규칙을 application-core/CLAUDE.md에 정본으로 두고 ArchUnit 2개와 생성 명령이 강제한다. compose Redis는 infra/redis-sdk ACL로 뜬다. 묶음별 결과는 리뷰 README 16절에 있다. 위험·한계: APP_FLYWAY_ENABLED가 dev·prod에도 적용된다. app.security 오타 키가 이제 기동을 막는다. SES 콜백 replay 창 기본값이 1시간이다. 템플릿 패키지 목록은 CLAUDE.md 표와 TemplatePackageOwnership 두 곳에 있고 일치 검사는 없다. 실제 CI runner 실행은 확인하지 못했다. 검증: ci, mainCheck, integrationCheck, -p optional-platforms ci integrationCheck, performanceCheck, releaseCheck(-PgitRevision), verify-compose-profile-contracts(18 lane) 통과. compose lane 실제 기동: local-fileserver, notification ingest·serving·handoff, local-redis, all-adapters(smoke 3개 포함). Refs: docs/reviews/2026-11-01-maturity-review/README.md 15·16절 BREAKING CHANGE: APP_FLYWAY_ENABLED가 dev·prod 프로필에도 적용되고, app.security의 모르는 키는 기동을 거부한다. MessageHandler에 schemaVersions()가 생겨 decode 목록을 handler 선언에서 만든다. --- docs/messaging/outbox-inbox.md | 5 + messaging/CLAUDE.md | 10 ++ .../api/delivery/MessageHandler.java | 22 +++ .../messaging/inbox/InboxMessageHandler.java | 7 + .../autoconfigure/MessageContracts.java | 53 +++++++- .../MessagingConfigurationCompiler.java | 18 ++- .../autoconfigure/MessagingEndpoint.java | 2 +- .../MessagingPublishConfiguration.java | 14 +- .../MessagingConsumeConfigurationTest.java | 126 ++++++++++++++++++ 9 files changed, 243 insertions(+), 14 deletions(-) diff --git a/docs/messaging/outbox-inbox.md b/docs/messaging/outbox-inbox.md index 7167b1e..6ec2d04 100644 --- a/docs/messaging/outbox-inbox.md +++ b/docs/messaging/outbox-inbox.md @@ -4,6 +4,8 @@ > DataSource 위 `JdbcInboxRepository`, `PlatformTransactionManager` 위 `TransactionRunner`)은 > `adapter:inbound:messaging`(`src/adapter/inbound/messaging/README.md`)이 둔다. platform starter는 두 > bean이 있을 때 `IdempotentConsumer`를 만들어 `INBOX_TRANSACTIONAL` destination의 handler를 감싼다. +> 그 leaf는 inbox 마이그레이션(`V1101`)만 자기 history 표로 적용하므로, 아래 "location 추가"는 platform +> outbox를 쓰는 배포의 이야기다. payload decode 목록은 handler bean의 선언으로 만든다. ## 두 패턴이 각각 무엇을 해결하는가 @@ -130,6 +132,9 @@ consume 계약은 `MessageHandler` 하나다. handler를 bean으로 등록하 - `Reject`는 at-most-once destination에서만 버리고, 그 밖에서는 dead letter로 보낸다. 실제 왕복·중복 제거·DLQ는 `MessagingKafkaConsumeQualificationTest`(Kafka + PostgreSQL Testcontainers)가 확인한다. +애플리케이션 경로(앱 outbox relay가 발행 → `adapter:inbound:messaging`이 조립한 inbox와 JPA 트랜잭션 → +handler)의 중복 전달·실패 재처리는 `InboxRedeliveryIntegrationTest`(lane +`messagingInboxRedeliveryIntegrationTest`)가 확인한다. ### 복합 키 diff --git a/messaging/CLAUDE.md b/messaging/CLAUDE.md index 14c58e8..8c8d2ac 100644 --- a/messaging/CLAUDE.md +++ b/messaging/CLAUDE.md @@ -30,6 +30,16 @@ leaf의 정확한 id는 registry에서 읽는다. family는 **디렉터리 이 JDBC이고 SQL은 `jsonb` · `FOR UPDATE SKIP LOCKED` · `ON CONFLICT` · `TIMESTAMPTZ`로 PostgreSQL 전용이다. `jpa`라는 이름은 사용하지 않는 기술을 광고하고, vendor 중립 port가 어디 있는지도 숨겼다. +### 공용 다이제스트 헬퍼를 복사해 두는 이유 (review 2026-11-01 01-11) + +`messaging-admin`(`HmacApprovalVerifier`, `PlanDigest`)과 `messaging-claim-check` +(`ClaimCheckIntegrityGuard`)는 SHA-256·HMAC-SHA256 계산을 자기 안에 둔다. 템플릿의 +`shared-contract` `digest/Sha256`·`HmacSha256`을 쓰지 않는 것은 의도다. 이 family는 이 애플리케이션의 +계층이 아니라 자기 API·SPI·composition을 가진 다른 제품이고(MSG-023 §6.2), `messaging:*` leaf는 +`domain-core`·`application-core`·`shared-contract` 어느 타입에도 의존하지 않는다. 헬퍼 하나 때문에 +registry edge를 주면 그 경계가 깨진다. 복사본을 고칠 때(키 길이 검사, constant-time 비교 등)는 +`shared-contract`의 정본과 같은 규칙인지 함께 본다. + ## Public surface 정책 - **vendor 타입을 public signature에 노출하면 그 의존성은 `api`로 선언한다.** 숨긴다고 타입이 diff --git a/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/MessageHandler.java b/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/MessageHandler.java index 0abdc89..5e3c3c3 100644 --- a/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/MessageHandler.java +++ b/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/MessageHandler.java @@ -1,6 +1,8 @@ package dev.caskeleton.messaging.api.delivery; +import dev.caskeleton.messaging.api.SchemaVersion; import dev.caskeleton.messaging.api.destination.MessageDestination; +import java.util.Set; import java.util.concurrent.CompletionStage; /** @@ -28,6 +30,26 @@ public interface MessageHandler { */ MessageDestination destination(); + /** + * The schema versions of {@link #destination()}'s message type that its payload class reads. + * + *

This declaration is the consumer's whole registration. The platform decodes a delivery only + * against a contract — message type and schema version — it knows the payload class for, and it + * builds that list from the handler beans: each version here, with the destination's message + * type, decodes into the destination's payload class. A service writes no registration code of + * its own, so a handler cannot exist while its messages are dead-lettered as undecodable for want + * of one. + * + *

A version the handler does not name is still refused ({@code SCHEMA_VERSION_NOT_REGISTERED}) + * rather than decoded into a class written for another version. A handler that reads a second + * version says so here when the producer starts sending it. + * + * @return the versions this handler reads; version 1 unless it declares otherwise + */ + default Set schemaVersions() { + return Set.of(new SchemaVersion(1)); + } + /** * Handles one delivery. * diff --git a/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/inbox/InboxMessageHandler.java b/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/inbox/InboxMessageHandler.java index 23c230f..0bd0055 100644 --- a/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/inbox/InboxMessageHandler.java +++ b/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/inbox/InboxMessageHandler.java @@ -1,11 +1,13 @@ package dev.caskeleton.messaging.inbox; +import dev.caskeleton.messaging.api.SchemaVersion; import dev.caskeleton.messaging.api.delivery.HandleResult; import dev.caskeleton.messaging.api.delivery.MessageDelivery; import dev.caskeleton.messaging.api.delivery.MessageHandler; import dev.caskeleton.messaging.api.destination.MessageDestination; import java.time.Instant; import java.util.Objects; +import java.util.Set; import java.util.concurrent.CompletableFuture; import java.util.concurrent.CompletionException; import java.util.concurrent.CompletionStage; @@ -71,6 +73,11 @@ public final class InboxMessageHandler implements MessageHandler { return delegate.destination(); } + @Override + public Set schemaVersions() { + return delegate.schemaVersions(); + } + @Override public CompletionStage handle(MessageDelivery delivery) { Objects.requireNonNull(delivery, "delivery must not be null"); diff --git a/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessageContracts.java b/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessageContracts.java index 82f9721..212ac85 100644 --- a/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessageContracts.java +++ b/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessageContracts.java @@ -1,11 +1,17 @@ package dev.caskeleton.messaging.autoconfigure; +import dev.caskeleton.messaging.api.SchemaVersion; +import dev.caskeleton.messaging.api.delivery.MessageHandler; +import dev.caskeleton.messaging.api.destination.MessageDestination; +import dev.caskeleton.messaging.api.error.MessagingConfigurationException; import dev.caskeleton.messaging.schema.MessageContractKey; +import java.util.Collection; +import java.util.LinkedHashMap; import java.util.Map; import java.util.Objects; /** - * What this deployment publishes: message type and schema version to payload class. + * The deployment's message contracts: message type and schema version to payload class. * *

A named holder rather than a bare {@code Map} bean, because {@code Map} is not a neutral * injection type in Spring — a {@code Map} injection point is interpreted as "every bean of @@ -13,6 +19,12 @@ import java.util.Objects; * into something nobody wrote. A holder makes the intent unambiguous to the container and to a * reader. * + *

A deployment registers what it publishes as a bean of this type. What it + * consumes it does not register at all: {@link #withConsumed} adds each handler bean's own + * declaration, so the codec decodes exactly what some handler said it reads (review 2026-11-01 + * 06-08 follow-up). A consumer whose payload type had to be registered here as well was a consumer + * whose messages were dead-lettered as undecodable whenever that second step was forgotten. + * *

Empty is the default and it is fail-closed: no message type can be encoded, and every publish * is refused at preparation. A codec that accepted an unregistered type would serialise whatever * object it was handed onto a topic that consumers compiled against a different shape will read — @@ -32,4 +44,43 @@ public record MessageContracts(Map> byKey) { public static MessageContracts none() { return new MessageContracts(Map.of()); } + + /** + * These contracts plus every contract the given handlers consume. + * + *

A handler names its message type and payload class in {@link MessageHandler#destination()} + * and the schema versions that class reads in {@link MessageHandler#schemaVersions()}; each + * version is one contract. The same contract declared twice with the same class is one entry. + * + * @param handlers the deployment's handler beans + * @return the combined contracts + * @throws MessagingConfigurationException when two declarations give one contract different + * payload classes — the codec holds one class per contract, so one of them would decode every + * message of that type into the wrong shape + */ + public MessageContracts withConsumed(Collection> handlers) { + Map> combined = new LinkedHashMap<>(byKey); + for (MessageHandler handler : handlers) { + MessageDestination destination = handler.destination(); + for (SchemaVersion version : handler.schemaVersions()) { + MessageContractKey key = new MessageContractKey(destination.messageType(), version); + Class declared = destination.payloadType(); + Class existing = combined.putIfAbsent(key, declared); + if (existing != null && !existing.equals(declared)) { + throw new MessagingConfigurationException( + "MESSAGING_CONTRACT_CONFLICT", + "contract " + + key.describe() + + " is declared as " + + existing.getName() + + " and as " + + declared.getName() + + " (handler for destination '" + + destination.name().value() + + "'); one contract decodes into one payload class"); + } + } + } + return new MessageContracts(combined); + } } diff --git a/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationCompiler.java b/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationCompiler.java index 2a24d32..fd46dd1 100644 --- a/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationCompiler.java +++ b/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationCompiler.java @@ -24,7 +24,6 @@ import java.util.Map; import java.util.Objects; import java.util.Optional; import java.util.Set; -import java.util.function.Supplier; /** * Turns the documented configuration into the objects the platform already validates. @@ -222,10 +221,9 @@ public final class MessagingConfigurationCompiler { broker.production(), broker.tlsEnabled(), security.hostnameVerification(), - credential(name, "producer", security.producer(), () -> true), - credential(name, "consumer", security.consumer(), () -> true), - Optional.ofNullable(security.admin()) - .map(admin -> credential(name, "admin", admin, () -> true)), + credential(name, "producer", security.producer()), + credential(name, "consumer", security.consumer()), + Optional.ofNullable(security.admin()).map(admin -> credential(name, "admin", admin)), new DestinationAccessPolicy( destinationNames(security.access().publishable()), destinationNames(security.access().consumable()), @@ -248,11 +246,11 @@ public final class MessagingConfigurationCompiler { } private static BrokerCredentialProfile credential( - String broker, - String role, - BrokerSecuritySettings.Credential credential, - Supplier required) { - if (credential == null && Boolean.TRUE.equals(required.get())) { + String broker, String role, BrokerSecuritySettings.Credential credential) { + // Every role that reaches here is required: the optional admin role is filtered out by its + // caller before the call. A "not required" branch would have nothing to return and fell + // through to dereference the missing credential. + if (credential == null) { throw configurationError( key("security", broker, role), "a configured broker needs a %s credential; the roles are separate so that a compromised " diff --git a/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingEndpoint.java b/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingEndpoint.java index 666cb4e..79f8518 100644 --- a/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingEndpoint.java +++ b/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingEndpoint.java @@ -23,7 +23,7 @@ import org.springframework.boot.actuate.endpoint.annotation.ReadOperation; * re-identification surface too. */ @Endpoint(id = "messaging") -public class MessagingEndpoint { +public final class MessagingEndpoint { private final ValidatedDestinationRegistry registry; private final MessagingAdmissionController admission; diff --git a/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingPublishConfiguration.java b/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingPublishConfiguration.java index 79995f1..471e32e 100644 --- a/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingPublishConfiguration.java +++ b/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingPublishConfiguration.java @@ -98,16 +98,26 @@ public class MessagingPublishConfiguration { * that accepted an unregistered type would serialise whatever object it was handed and put bytes * on a topic that consumers compiled against a different shape will read. * + *

To those the handler beans add what they consume ({@link MessageContracts#withConsumed}): + * the decode list is what the handlers declare, so a service registers nothing to consume. The + * handlers are resolved here, so a handler whose own dependencies reach back to the publisher is + * a dependency cycle, and Spring refuses it at startup naming both beans. + * * @param contracts the declared message contracts, if the deployment registered any + * @param handlers the deployment's message handlers, whose declarations are decoded * @return the registry, defaulting to JSON */ @Bean @ConditionalOnMissingBean(dev.caskeleton.messaging.schema.MessageCodecRegistry.class) public dev.caskeleton.messaging.runtime.RegisteredMessageCodecs messagingCodecs( - ObjectProvider contracts) { + ObjectProvider contracts, + ObjectProvider> handlers) { return dev.caskeleton.messaging.runtime.RegisteredMessageCodecs.of( dev.caskeleton.messaging.schema.json.JacksonMessageCodec.of( - contracts.getIfAvailable(MessageContracts::none).byKey())); + contracts + .getIfAvailable(MessageContracts::none) + .withConsumed(handlers.orderedStream().toList()) + .byKey())); } /** diff --git a/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingConsumeConfigurationTest.java b/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingConsumeConfigurationTest.java index b8471f8..5976624 100644 --- a/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingConsumeConfigurationTest.java +++ b/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingConsumeConfigurationTest.java @@ -1,13 +1,23 @@ package dev.caskeleton.messaging.autoconfigure; import static org.assertj.core.api.Assertions.assertThat; +import static org.assertj.core.api.Assertions.catchThrowable; +import dev.caskeleton.messaging.api.ContentType; import dev.caskeleton.messaging.api.MessageType; +import dev.caskeleton.messaging.api.SchemaVersion; import dev.caskeleton.messaging.api.delivery.HandleResult; import dev.caskeleton.messaging.api.delivery.MessageDelivery; import dev.caskeleton.messaging.api.delivery.MessageHandler; import dev.caskeleton.messaging.api.destination.DestinationName; import dev.caskeleton.messaging.api.destination.MessageDestination; +import dev.caskeleton.messaging.api.error.MessageValidationException; +import dev.caskeleton.messaging.schema.MessageCodec; +import dev.caskeleton.messaging.schema.MessageCodecRegistry; +import dev.caskeleton.messaging.schema.MessageContractKey; +import java.nio.charset.StandardCharsets; +import java.util.Map; +import java.util.Set; import java.util.concurrent.CompletableFuture; import java.util.concurrent.CompletionStage; import org.junit.jupiter.api.DisplayName; @@ -100,6 +110,122 @@ class MessagingConsumeConfigurationTest { .hasMessageContaining("IdempotentConsumer")); } + @Test + @DisplayName("handler bean이 선언한 메시지 타입과 payload class는 따로 등록하지 않아도 decode된다") + void aHandlerBeansDeclaredContractIsDecodedWithoutAnyRegistration() { + // given: a handler for order.created and no MessageContracts bean at all + var consuming = + runner + .withPropertyValues("app.messaging.destinations.order-events.consumer.group=projection") + .withBean( + "ordersHandler", + MessageHandler.class, + () -> handler(OrderCreated.class, Set.of(new SchemaVersion(1)))); + + // when + consuming.run( + context -> { + OrderCreated decoded = + json(context.getBean(MessageCodecRegistry.class)) + .decode( + new MessageType("order.created"), + new SchemaVersion(1), + "{\"orderId\":\"o-1\"}".getBytes(StandardCharsets.UTF_8), + OrderCreated.class); + + // then + assertThat(decoded).isEqualTo(new OrderCreated("o-1")); + }); + } + + @Test + @DisplayName("handler가 선언하지 않은 schema version은 그 class로 decode하지 않고 거부한다") + void aSchemaVersionTheHandlerDoesNotDeclareIsRefused() { + // given: the handler reads version 1 only + var consuming = + runner + .withPropertyValues("app.messaging.destinations.order-events.consumer.group=projection") + .withBean( + "ordersHandler", + MessageHandler.class, + () -> handler(OrderCreated.class, Set.of(new SchemaVersion(1)))); + + // when + consuming.run( + context -> { + Throwable refused = + catchThrowable( + () -> + json(context.getBean(MessageCodecRegistry.class)) + .decode( + new MessageType("order.created"), + new SchemaVersion(2), + "{\"orderId\":\"o-1\"}".getBytes(StandardCharsets.UTF_8), + OrderCreated.class)); + + // then + assertThat(refused) + .isInstanceOf(MessageValidationException.class) + .hasMessageContaining("order.created v2"); + }); + } + + @Test + @DisplayName("등록된 계약과 handler가 같은 type·version에 다른 class를 선언하면 기동을 거부한다") + void aHandlerThatDeclaresAnotherClassForARegisteredContractFailsStartup() { + // given: order.created v1 registered as String, and a handler reading it as OrderCreated + var conflicting = + runner + .withPropertyValues("app.messaging.destinations.order-events.consumer.group=projection") + .withBean( + MessageContracts.class, + () -> + new MessageContracts( + Map.of(MessageContractKey.of("order.created", 1), String.class))) + .withBean( + "ordersHandler", + MessageHandler.class, + () -> handler(OrderCreated.class, Set.of(new SchemaVersion(1)))); + + // when + conflicting.run( + context -> + // then + assertThat(context) + .hasFailed() + .getFailure() + .rootCause() + .hasMessageContaining("order.created v1") + .hasMessageContaining(OrderCreated.class.getName())); + } + + /** The payload a consumer of {@code order.created} reads. */ + record OrderCreated(String orderId) {} + + private static MessageCodec json(MessageCodecRegistry codecs) { + return codecs.find(ContentType.JSON).orElseThrow(); + } + + private static MessageHandler handler(Class payload, Set versions) { + return new MessageHandler<>() { + @Override + public MessageDestination destination() { + return new MessageDestination<>( + new DestinationName("order-events"), new MessageType("order.created"), payload); + } + + @Override + public Set schemaVersions() { + return versions; + } + + @Override + public CompletionStage handle(MessageDelivery delivery) { + return CompletableFuture.completedFuture(HandleResult.success()); + } + }; + } + private static MessageHandler handler() { return new MessageHandler<>() { @Override From a32b67a2ceacfe34eb8bf52bb78356183a325240 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Tue, 3 Nov 2026 23:29:35 +0900 Subject: [PATCH 4/6] =?UTF-8?q?fix!:=20=EC=9E=AC=EB=A6=AC=EB=B7=B0?= =?UTF-8?q?=EA=B0=80=20=EC=B0=BE=EC=9D=80=20=EA=B2=B0=ED=95=A8=EA=B3=BC=20?= =?UTF-8?q?=EC=83=89=EC=9D=B8=EC=97=90=EC=84=9C=20=EB=B9=A0=EC=A1=8C?= =?UTF-8?q?=EB=8D=98=20=EB=B0=9C=EA=B2=AC=205=EA=B1=B4=EC=9D=84=20?= =?UTF-8?q?=EA=B3=A0=EC=B9=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 성숙도 리뷰 수정을 다시 읽은 재리뷰(Critical 0, 회귀 0)가 Important 27건·Minor 41건을 찾았다. 수정이 새로 만든 결함이 많았다. @SystemInvoked가 권한 규칙의 탈출구가 됐고, 데모 계정 거부가 정확히 prod일 때만 걸렸고, outbox 순서 번호가 업그레이드 때 뒤로 갔고, GraphQL union 아래 복잡도가 0이었고, 서블릿 오류 응답이 success:true로 나갔고, 호출자 deadline이 breaker를 열었다. 원래 리뷰 색인이 06 영역 발견 5건(06-10~14)을 빠뜨려 그동안 처리되지 않았다. 방법: 영역별 7묶음이 test-driven-development 절차로 실패 테스트를 먼저 쓰고 고쳤다. 결정은 재리뷰 README 4절에 적었다: 순서 번호는 V21이 기록한 전역 floor부터, 데모 계정은 local·test·demo 허용 목록, @SystemInvoked bean은 기동 실패, complete 단계 실패는 IDEMPOTENCY_COMPLETION_UNKNOWN(결과 불명), 캐시 조건부 쓰기는 별도 SCRIPT lane, strict lane 정책은 build cache 입력, 끝나지 않는 재시도 행은 원인 코드·지표·PARKED 절차. 레지스트리가 선언만 하고 아무 코드도 내보내지 않던 redis.capability.* 지표 6개는 빼고 runbook을 실제 지표(redis.lane.*) 기준으로 고쳤다. 위험·한계: V21을 V22 없이 직접 고쳤다(어느 배포에도 아직 없음). 이 브랜치의 V21을 적용한 개발 DB는 다시 만들어야 한다. 서블릿 오류 디스패치를 보안 체인이 허용한다. 발행·저장소 포트 시그니처가 바뀌어 파생 서비스 코드가 깨진다. prod에서 fixture-로 시작하는 설정값은 기동을 막는다. httpclient failure-injection lane의 main 단계 중복 실행은 이전 결정대로 남겼다. 실제 CI runner 실행은 확인하지 못했다. 검증: ci, mainCheck, :integrationCheck, -p optional-platforms ci integrationCheck performanceCheck, :performanceCheck, :releaseCheck (-PgitRevision), verify-compose-profile-contracts(18 lane) 통과. 첫 실행의 실패 2건(FindSecBugs 1, sample 동시 생성 테스트의 v4 event id)은 고친 뒤 ci·integrationCheck·mainCheck를 다시 돌려 통과했다. Refs: docs/reviews/2026-11-03-rereview/README.md 3·4·6·7절 BREAKING CHANGE: outbox 발행 포트와 저장소 포트 시그니처, 순서 번호 첫 값(V21 floor 다음), 샘플 데모 계정 프로필 허용 목록, 새 오류 코드 IDEMPOTENCY_COMPLETION_UNKNOWN, prod의 fixture- 값 거부, 기동 rule은 static·의존 없음이어야 한다. --- docs/messaging/configuration-reference.md | 4 +- docs/messaging/outbox-inbox.md | 20 +++++ messaging/CLAUDE.md | 25 ++++++ .../api/error/FailureDescriptor.java | 8 ++ .../kafka/KafkaConsumerRegistrar.java | 43 +++++++-- .../kafka/KafkaPublishFailureClassifier.java | 12 ++- .../kafka/KafkaQuarantinePublisher.java | 18 +++- .../kafka/KafkaConsumerRegistrarTest.java | 89 ++++++++++++++++++- .../runtime/DefaultMessagePublisher.java | 2 +- .../KafkaDeadLetterQuarantine.java | 8 +- .../MessagingShutdownLifecycle.java | 17 ++-- 11 files changed, 218 insertions(+), 28 deletions(-) diff --git a/docs/messaging/configuration-reference.md b/docs/messaging/configuration-reference.md index 3fc19e9..07130a2 100644 --- a/docs/messaging/configuration-reference.md +++ b/docs/messaging/configuration-reference.md @@ -26,7 +26,9 @@ producing-service identity다. ## Outbox -outbox는 canonical 하나다(2026-09-28). use case가 `IntegrationEventEncoderPort`로 만든 +application의 발행 경로는 하나다(2026-09-28): `outbox_event` 표와 `composition:outbox-relay`. vendored +platform의 `messaging_outbox`(`outbox-inbox.md`)는 이 경로에 쓰이지 않는다 — 두 모델의 상태 대응은 +`outbox-inbox.md` 머리의 표에 있다. use case가 `IntegrationEventEncoderPort`로 만든 `ValidatedIntegrationEvent`를 `OutboxAppendPort`로 append하고, relay는 claim한 row의 exact envelope bytes를 `IntegrationEventPublishPort`로 보낸다. 예전의 `app.outbox.canonical-transport-enabled` gate와 legacy `MessageBroker → KafkaSender` 경로는 삭제됐다. 발행할 contract의 logical destination마다 diff --git a/docs/messaging/outbox-inbox.md b/docs/messaging/outbox-inbox.md index 6ec2d04..08f1818 100644 --- a/docs/messaging/outbox-inbox.md +++ b/docs/messaging/outbox-inbox.md @@ -1,5 +1,25 @@ # Outbox · Inbox +> **이 문서의 Outbox는 vendored messaging platform의 outbox다**(`messaging_outbox` 표, +> `messaging-reliability`의 `OutboxRelay`). 이 템플릿 application이 쓰는 outbox는 그것이 아니다. +> application은 `outbox_event` 표(`adapter:outbound:persistence-jpa`)에 append하고, relay는 +> `composition:outbox-relay`가 돌린다. 그 동작과 운영은 `docs/manual/09-outbox-events.md`, +> `src/composition/outbox-relay/README.md`, `docs/runbooks/outbox-dead-letter.md`, +> `docs/runbooks/outbox-publish-failed.md`에 있다. platform outbox는 소유자 결정으로 제품 안에 남아 +> 있지만, platform outbox repository bean이 없으면 그 relay는 만들어지지 않는다(리뷰 2026-11-01 06-11). +> +> 두 모델은 같은 이름의 상태가 반대 뜻이다. 이름으로 옮기면 확정 거부는 영원히 재시도되고 응답 없는 +> 메시지는 버려진다. 대응은 아래 표 하나로만 읽는다(`OutboxPublishOutcome` Javadoc과 같은 내용). +> +> | 일어난 일 | application `outbox_event` | platform `messaging_outbox` | +> |---|---|---| +> | broker가 확인했다 | `PUBLISHED` | `PUBLISHED` | +> | 응답이 없었다(저장됐을 수 있음) | `FAILED`(재시도, 예산 안 씀, 끝 없음) | `AMBIGUOUS`(재시도, 예산을 다 쓰면 `EXHAUSTED`) | +> | 지금만 거부됐다(종료·포화·credential) | `FAILED`(재시도, 예산 안 씀, 끝 없음) | `FAILED`(종단) | +> | 확정 거부됐다(같은 payload는 또 거부) | `DEAD`(종단, 수동 처분) | `FAILED`(종단) | +> | publisher가 예외를 던졌고 시도 예산을 다 썼다 | `DEAD`(종단, 수동 처분) | `EXHAUSTED`(종단) | +> | 운영자가 재시도를 멈췄다 | `PARKED`(수동 재개·skip) | 없음 | +> > **이 템플릿 application의 소비 경로**: application의 `MessageHandler`와 inbox 부품(애플리케이션 > DataSource 위 `JdbcInboxRepository`, `PlatformTransactionManager` 위 `TransactionRunner`)은 > `adapter:inbound:messaging`(`src/adapter/inbound/messaging/README.md`)이 둔다. platform starter는 두 diff --git a/messaging/CLAUDE.md b/messaging/CLAUDE.md index 8c8d2ac..931c282 100644 --- a/messaging/CLAUDE.md +++ b/messaging/CLAUDE.md @@ -40,6 +40,31 @@ JDBC이고 SQL은 `jsonb` · `FOR UPDATE SKIP LOCKED` · `ON CONFLICT` · `TIMES registry edge를 주면 그 경계가 깨진다. 복사본을 고칠 때(키 길이 검사, constant-time 비교 등)는 `shared-contract`의 정본과 같은 규칙인지 함께 본다. +### Publish retryability of authentication and authorization (review 2026-11-01 06-01) + +이 제품 안에는 같은 category에 대한 재시도 규칙이 둘 있다. 의도다. + +- category 기본값: `FailureDescriptor.defaultRetryable(AUTHENTICATION | AUTHORIZATION) = false`. 소비 쪽 + 재시도 엔진(`DefaultRetryDecisionEngine`)은 policy가 category를 따로 정하지 않으면 이 기본값과 + descriptor의 `retryable`을 둘 다 요구한다. 그래서 인가받지 못한 메시지의 재전달은 지금도 재시도하지 않는다. +- publish 거부의 `retryable`: `KafkaPublishFailureClassifier`는 인증·인가 거부에 `retryable = true`를 붙인다. + broker가 레코드를 저장하지 않았고, credential 교체나 application보다 늦게 배포된 ACL은 몇 분 동안 모든 + publish를 거부한 뒤 멈추기 때문이다. `retryable`을 믿는 publisher가 그 몇 분 동안의 레코드를 영구 보류하지 + 않게 하려는 것이다. + +06-01 수정이 이 제품에서 바꾼 것(모두 publish 경로, 소비 경로 동작은 그대로): + +- `KafkaPublishFailureClassifier`: 인증·인가 거부를 `retryable = true`로. +- `DefaultMessagePublisher`: runtime이 없을 때의 거부(`PUBLISH_RUNTIME_UNAVAILABLE`)를 `retryable = true`로. +- `KafkaMessagingTransport`: 닫힌 transport의 거부(`KAFKA_TRANSPORT_CLOSED`)를 `retryable = true`로. +- `MessagingShutdownLifecycle.PHASE`: platform 밖 relay의 순서 테스트가 참조하도록 public. + +버린 대안: vendored 제품은 그대로 두고 application bridge(ACL)가 category를 보고 "인증·인가면 재시도"로 +번역하는 것. 버린 이유: `retryable`은 이 제품이 "같은 레코드를 나중에 다시 보내면 받아질 수 있나"를 말하는 +자리다. bridge가 category로 그 판단을 다시 하면 같은 사실을 제품과 bridge가 따로 정하고, 이 제품의 +`PublishResult`를 읽는 다른 호출자는 bridge와 다른 답을 본다. 대신 이 제품 주석은 소비자 이름(application +relay, `composition:outbox-relay`)을 부르지 않는다 — "flag를 믿는 publisher"로 쓴다(재리뷰 2026-11-03 RR-05-07). + ## Public surface 정책 - **vendor 타입을 public signature에 노출하면 그 의존성은 `api`로 선언한다.** 숨긴다고 타입이 diff --git a/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/FailureDescriptor.java b/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/FailureDescriptor.java index 5c00b10..ff8dd47 100644 --- a/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/FailureDescriptor.java +++ b/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/error/FailureDescriptor.java @@ -61,6 +61,14 @@ public record FailureDescriptor( * automatically: each of them fails identically on every redelivery, so retrying only multiplies * the load while the message is still poison. * + *

A default, not a rule every descriptor follows. A publish rejection may carry {@code + * retryable = true} with an authentication or authorization category: the broker did not store + * the record, and a credential being rotated or an ACL deployed after the application refuses + * every publish for a few minutes and then stops (the Kafka publish classifier). The + * consumer-side retry engine requires this default as well as the flag unless its policy names + * the category, so redelivery of an unauthorised message is still not retried; only a publisher + * that reads {@link #retryable()} sees the difference. + * * @param category the classification * @return true when automatic retry is allowed by default */ diff --git a/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaConsumerRegistrar.java b/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaConsumerRegistrar.java index 4b85f2f..4e96018 100644 --- a/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaConsumerRegistrar.java +++ b/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaConsumerRegistrar.java @@ -344,10 +344,17 @@ public final class KafkaConsumerRegistrar implements TransportConsumerRegistrati // A decode failure is not a handler failure and must not be retried forever. The // offset may only advance once the record exists somewhere else, so an unavailable // quarantine leaves it uncommitted rather than dropping the message. - if (quarantine.quarantine(record, undecodable)) { + // It will never decode, however often it is redriven: DESERIALIZATION, not the + // POISON_MESSAGE of a handler that ran out of attempts (review 2026-11-01 06-14). + if (quarantine.quarantine( + record, + dev.caskeleton.messaging.api.error.FailureCategory.DESERIALIZATION, + undecodable)) { settlement.acknowledgeAfterQuarantine(); } else { - settlement.requeueAfterFailure(undecodable); + settlement.requeueAfterFailure( + undecodable, + dev.caskeleton.messaging.api.error.FailureCategory.DESERIALIZATION); } coordinator.release(partition); shutdown.endWork(); @@ -682,6 +689,7 @@ public final class KafkaConsumerRegistrar implements TransportConsumerRegistrati retryOrQuarantine( new IllegalStateException( "the handler asked for another attempt and the retry budget is spent"), + dev.caskeleton.messaging.api.error.FailureCategory.POISON_MESSAGE, delay)); } @@ -715,11 +723,21 @@ public final class KafkaConsumerRegistrar implements TransportConsumerRegistrati * that exists nowhere else — which is why a production destination must have one. */ private void requeueAfterFailure(Throwable reason) { + requeueAfterFailure(reason, exhaustedCategory(reason)); + } + + /** + * {@link #requeueAfterFailure(Throwable)} under a category the caller already knows: a record + * that could not be decoded stays {@code DESERIALIZATION} when its first quarantine write was + * not confirmed and it reaches quarantine again through the retry path. + */ + private void requeueAfterFailure( + Throwable reason, dev.caskeleton.messaging.api.error.FailureCategory category) { if (!terminal.compareAndSet(null, "requeue")) { // The handler settled before it failed or before its late completion; that answer stands. return; } - retryOrQuarantine(reason, Duration.ZERO); + retryOrQuarantine(reason, category, Duration.ZERO); } /** @@ -730,11 +748,13 @@ public final class KafkaConsumerRegistrar implements TransportConsumerRegistrati * being retried — the offset may not advance past a message that exists nowhere else. */ private dev.caskeleton.messaging.api.settlement.SettlementResult retryOrQuarantine( - Throwable reason, Duration requested) { + Throwable reason, + dev.caskeleton.messaging.api.error.FailureCategory category, + Duration requested) { FailedOffset key = new FailedOffset(partition, offset); int attempt = failures.merge(key, 1, Integer::sum); dev.caskeleton.messaging.policy.RetryPolicy retry = spec.profile().retry(); - if (attempt >= retry.maxAttempts() && quarantine.quarantine(record, reason)) { + if (attempt >= retry.maxAttempts() && quarantine.quarantine(record, category, reason)) { failures.remove(key); settlements.enqueue( new KafkaSettlementCommand( @@ -751,6 +771,19 @@ public final class KafkaConsumerRegistrar implements TransportConsumerRegistrati return enqueueRequeue(backoff); } + /** + * The category a record that ran out of attempts is quarantined under: its last failure's own, + * when that failure is a platform one and so carries a classification — a transient one tells a + * redrive the record may pass now — and {@code POISON_MESSAGE}, the platform's name for "keeps + * failing its consumer", when it is not. + */ + private static dev.caskeleton.messaging.api.error.FailureCategory exhaustedCategory( + Throwable reason) { + return reason instanceof dev.caskeleton.messaging.api.error.MessagingException classified + ? classified.category() + : dev.caskeleton.messaging.api.error.FailureCategory.POISON_MESSAGE; + } + private dev.caskeleton.messaging.api.settlement.SettlementResult enqueueRequeue( Duration delay) { retries.pauseUntil(partition, offset, delay, clock.instant()); diff --git a/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaPublishFailureClassifier.java b/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaPublishFailureClassifier.java index 0eea955..d6569fd 100644 --- a/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaPublishFailureClassifier.java +++ b/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaPublishFailureClassifier.java @@ -67,10 +67,14 @@ public final class KafkaPublishFailureClassifier { *

Authentication and authorization prove the broker did not store the record, but not that it * will refuse it again: a credential being rotated, or an ACL deployed after the application, * fails every publish this way for a few minutes and then stops. Marked not retryable, a - * publisher that trusts the flag — the application's outbox relay does — parks every record sent - * in those minutes. A credential that is simply wrong is retried too, and the outbox then holds - * its rows FAILED with an alert every retry — recoverable once the credential is fixed, where - * DEAD rows needed a manual reset each. + * publisher that trusts the flag parks every record sent in those minutes. A credential that is + * simply wrong is retried too, for as long as it stays wrong; the descriptor's code names it, so + * a caller can tell that retry from a rotation and stop it. + * + *

This flag departs from {@link FailureDescriptor#defaultRetryable} on purpose, for publish + * only: that default says an authentication or authorization failure is not retried, and it still + * governs consumption, where the retry engine requires both. See {@code src/messaging/CLAUDE.md} + * "Publish retryability of authentication and authorization". */ private static boolean mayPassOnRetry(Throwable cause) { return cause instanceof AuthenticationException || cause instanceof AuthorizationException; diff --git a/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaQuarantinePublisher.java b/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaQuarantinePublisher.java index 20489c9..af09f0e 100644 --- a/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaQuarantinePublisher.java +++ b/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaQuarantinePublisher.java @@ -1,5 +1,6 @@ package dev.caskeleton.messaging.kafka; +import dev.caskeleton.messaging.api.error.FailureCategory; import org.apache.kafka.clients.consumer.ConsumerRecord; /** @@ -18,11 +19,22 @@ import org.apache.kafka.clients.consumer.ConsumerRecord; public interface KafkaQuarantinePublisher { /** - * Writes an undecodable record somewhere durable. + * Writes a record the consumer will not deliver somewhere durable, under the reason it gives. * + *

The category is the caller's, because only the caller knows which of two very different + * things happened: the record could not be rebuilt at all ({@link + * FailureCategory#DESERIALIZATION}), or its handler failed until the attempt budget ran out — + * under the failure's own category when it carries one, {@link FailureCategory#POISON_MESSAGE} + * when it does not. Both were written as {@code POISON_MESSAGE}, so a redrive could not tell a + * message that will never decode from one an outage kept failing (review 2026-11-01 06-14). + * + * @param record the record as it arrived + * @param category why it is quarantined, written as the failure-category header + * @param reason the failure; its type is written as the failure-code header * @return true when the write is confirmed, so the source offset may be committed */ - boolean quarantine(ConsumerRecord record, Throwable reason); + boolean quarantine( + ConsumerRecord record, FailureCategory category, Throwable reason); /** * The default: nothing is configured, so nothing may be committed past. @@ -37,7 +49,7 @@ public interface KafkaQuarantinePublisher { /** Holds the single "not configured" quarantine. */ final class Unavailable { - private static final KafkaQuarantinePublisher INSTANCE = (record, reason) -> false; + private static final KafkaQuarantinePublisher INSTANCE = (record, category, reason) -> false; private Unavailable() {} } diff --git a/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaConsumerRegistrarTest.java b/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaConsumerRegistrarTest.java index f5580a5..edd7769 100644 --- a/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaConsumerRegistrarTest.java +++ b/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaConsumerRegistrarTest.java @@ -3,6 +3,7 @@ package dev.caskeleton.messaging.kafka; import static org.assertj.core.api.Assertions.assertThat; import dev.caskeleton.messaging.api.MessageId; +import dev.caskeleton.messaging.api.error.FailureCategory; import dev.caskeleton.messaging.api.header.ReservedHeaders; import dev.caskeleton.messaging.policy.OrderingImpact; import dev.caskeleton.messaging.policy.RetryMode; @@ -258,7 +259,7 @@ class KafkaConsumerRegistrarTest { registrar( KafkaContractHarness.profile(), this::fail, - (record, reason) -> quarantined.add(record.offset()), + (record, category, reason) -> quarantined.add(record.offset()), () -> NOW); assign(); addRecord(10); @@ -274,6 +275,29 @@ class KafkaConsumerRegistrarTest { .hasValue(11L); } + @Test + @DisplayName("handler가 시도 예산을 다 쓴 레코드는 그 실패의 분류로 격리하고 분류가 없으면 POISON_MESSAGE로 적는다") + void aDeliveryThatSpentItsBudgetIsQuarantinedUnderItsFailuresCategory() { + // given: a handler that fails with a plain exception every time + List categories = new ArrayList<>(); + KafkaConsumerRegistrar registrar = + registrar( + KafkaContractHarness.profile(), + this::fail, + (record, category, reason) -> categories.add(category), + () -> NOW); + assign(); + addRecord(10); + registrar.pollOnce(NOW); + handlers.runAll(); + + // when + registrar.pollOnce(NOW); + + // then + assertThat(categories).containsExactly(FailureCategory.POISON_MESSAGE); + } + @Test @DisplayName("handler가 요청한 requeue도 시도 횟수를 세어 예산을 쓰면 quarantine 후 commit된다") void aDeliveryItsHandlerKeepsRequeueingSpendsTheBudgetAndIsQuarantined() { @@ -283,7 +307,7 @@ class KafkaConsumerRegistrarTest { registrar( KafkaContractHarness.profile(), this::requeue, - (record, reason) -> quarantined.add(record.offset()), + (record, category, reason) -> quarantined.add(record.offset()), () -> NOW); assign(); addRecord(10); @@ -470,7 +494,7 @@ class KafkaConsumerRegistrarTest { handlers, new GracefulShutdownCoordinator(Duration.ofSeconds(30)), Duration.ofMillis(1), - (record, reason) -> { + (record, category, reason) -> { quarantined.add(record.offset()); return true; })) { @@ -486,6 +510,65 @@ class KafkaConsumerRegistrarTest { } } + /** + * A record that cannot be rebuilt into an envelope will never decode, however often it is + * redriven; the one whose handler ran out of attempts may pass once the outage is over. They were + * both written as {@code POISON_MESSAGE} (review 2026-11-01 06-14). + */ + @Test + @DisplayName("envelope로 되살릴 수 없는 레코드는 시도 예산 소진과 다른 DESERIALIZATION으로 격리한다") + void anUndecodableRecordIsQuarantinedAsDeserializationNotAsPoison() { + // given + List categories = new ArrayList<>(); + try (KafkaConsumerRegistrar registrar = + new KafkaConsumerRegistrar( + new TransportConsumerSpec(KafkaContractHarness.profile(), this::settleImmediately), + consumer, + handlers, + new GracefulShutdownCoordinator(Duration.ofSeconds(30)), + Duration.ofMillis(1), + (record, category, reason) -> categories.add(category))) { + assign(); + addRecordWithoutIdentityHeaders(10); + registrar.pollOnce(NOW); + + // when + handlers.runAll(); + + // then + assertThat(categories).containsExactly(FailureCategory.DESERIALIZATION); + } + } + + @Test + @DisplayName("격리 쓰기가 한 번 실패해 재시도로 넘어간 읽을 수 없는 레코드도 DESERIALIZATION으로 격리한다") + void anUndecodableRecordStaysDeserializationWhenItsQuarantineIsRetried() { + // given: the first quarantine write is not confirmed, so the record goes round the retry path + List categories = new ArrayList<>(); + try (KafkaConsumerRegistrar registrar = + new KafkaConsumerRegistrar( + new TransportConsumerSpec(KafkaContractHarness.profile(), this::settleImmediately), + consumer, + handlers, + new GracefulShutdownCoordinator(Duration.ofSeconds(30)), + Duration.ofMillis(1), + (record, category, reason) -> { + categories.add(category); + return categories.size() > 1; + })) { + assign(); + addRecordWithoutIdentityHeaders(10); + registrar.pollOnce(NOW); + + // when + handlers.runAll(); + + // then + assertThat(categories) + .containsExactly(FailureCategory.DESERIALIZATION, FailureCategory.DESERIALIZATION); + } + } + @Test @DisplayName("one partition hitting its ceiling does not abandon the other's records") void oneSaturatedPartitionDoesNotAbandonAnother() { diff --git a/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisher.java b/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisher.java index a51f9fe..5c4341e 100644 --- a/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisher.java +++ b/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisher.java @@ -265,7 +265,7 @@ public final class DefaultMessagePublisher implements MessagePublisher, EncodedM admission.complete(destination.name().value()); // No runtime to send through — the registry closed during shutdown, or none is installed // yet. Nothing about the message was wrong, so the refusal is marked retryable: a caller that - // trusts the flag, as the application's outbox relay does, retries it instead of parking it. + // trusts the flag retries it instead of parking it. return refused( new FailureDescriptor( FailureCategory.TRANSIENT_INFRASTRUCTURE, diff --git a/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaDeadLetterQuarantine.java b/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaDeadLetterQuarantine.java index 8185ef6..85ad9c2 100644 --- a/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaDeadLetterQuarantine.java +++ b/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaDeadLetterQuarantine.java @@ -1,5 +1,6 @@ package dev.caskeleton.messaging.autoconfigure; +import dev.caskeleton.messaging.api.error.FailureCategory; import dev.caskeleton.messaging.api.header.ReservedHeaders; import dev.caskeleton.messaging.kafka.KafkaQuarantinePublisher; import java.nio.charset.StandardCharsets; @@ -38,11 +39,14 @@ final class KafkaDeadLetterQuarantine implements KafkaQuarantinePublisher { } @Override - public boolean quarantine(ConsumerRecord record, Throwable reason) { + public boolean quarantine( + ConsumerRecord record, FailureCategory category, Throwable reason) { RecordHeaders headers = new RecordHeaders(record.headers().toArray()); headers.remove(ReservedHeaders.FAILURE_CATEGORY); headers.remove(ReservedHeaders.FAILURE_CODE); - headers.add(ReservedHeaders.FAILURE_CATEGORY, bytes("POISON_MESSAGE")); + headers.add( + ReservedHeaders.FAILURE_CATEGORY, + bytes(category == null ? FailureCategory.POISON_MESSAGE.name() : category.name())); headers.add( ReservedHeaders.FAILURE_CODE, bytes(reason == null ? "UNKNOWN" : reason.getClass().getSimpleName())); 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 7efaa47..147c266 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 @@ -29,14 +29,14 @@ 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. + * The phase this drain stops in: {@link #getPhase()}. Public so a relay outside the platform — a + * publisher whose production code may not name this type — can be held above it by a test that + * does name it. */ public static final int PHASE = Integer.MAX_VALUE - 1024; + /** How often the drain is re-checked. Short enough that a fast drain is not padded. */ private static final Duration POLL = Duration.ofMillis(50); private final MessagingAdmissionController admission; @@ -120,11 +120,10 @@ public final class MessagingShutdownLifecycle implements SmartLifecycle { * 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 relays' phase for the * mirror-image reason: refusing admission while a relay pass is mid-publish turns that pass's - * 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. + * rows into refusals. The platform's own relay ({@code MessagingOutboxRelayLifecycle}, built only + * when a platform outbox repository exists) stands above it, and so must any relay outside the + * platform that publishes through it: a phase above {@link #PHASE}, finishing the publish it is + * in before this phase runs. * * @return the lifecycle phase, {@link #PHASE} */ From a596504e2be85168c454869107e96783404f5858 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Wed, 4 Nov 2026 01:47:50 +0900 Subject: [PATCH 5/6] =?UTF-8?q?fix!:=202=EC=B0=A8=20=EC=9E=AC=EB=A6=AC?= =?UTF-8?q?=EB=B7=B0=EA=B0=80=20=EC=B0=BE=EC=9D=80=20=EA=B2=B0=ED=95=A8=20?= =?UTF-8?q?29=EA=B1=B4=EC=9D=84=20=EA=B3=A0=EC=B9=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 재리뷰 수정 커밋(a32b67a2)만 다시 본 2차 재리뷰가 Important 7건, Minor 22건을 찾았다. 결과 불명 503 뒤 같은 키를 다시 보내면 Redis store가 lease 지난 실행을 넘겨받아 작업을 다시 돌렸다. replay TTL이 lease보다 짧으면 lease 도중 key가 사라져 같은 키가 두 번 실행됐다. @SystemInvoked 규칙이 매뉴얼 09장의 이벤트 소비 경로까지 막았다. V22가 outbox_event에 가장 강한 잠금을 lock_timeout 없이 걸었다. prod의 fixture- 거부가 HOSTNAME 같은 비밀 아닌 값까지 막았다. 데모 허용 목록의 test·demo 프로필로 sample이 뜨지 않았다. 기동 rule bean의 @Value 필드가 조용히 null이 됐다. 방법: 영역별 4묶음이 test-driven-development 절차로 실패 테스트를 먼저 쓰고 고쳤다. 결정은 재리뷰 README 9.1절이다. - 두 멱등성 store가 같은 계약을 따른다. lease가 지난 실행 기록은 다시 돌리지 않고 포기로 표시해 500 RECOVERY_REQUIRED로 답한다. 기록 수명은 lease + replay TTL이고, replay-ttl < processing-lease면 기동이 실패한다. - 사용자 transport만 @SystemInvoked use case에 닿지 못한다. 메시지 handler·scheduler는 새 표시 @SystemCaller(reason)를 달고 use case를 생성자에서 new로 만든다. 매뉴얼 경로를 테스트로 고정했다. - 아직 어디에도 적용되지 않은 마이그레이션(V20·V22·알림 V11~V13·sample V8_1·grpc V002·V003)에 lock_timeout 5s를 넣고, 텍스트 검사기와 실 PG lane을 더했다. 이미 배포된 24개는 동결 목록으로 둔다. - fixture- 검사는 비밀로 분류된 값만 본다. sample은 local·test·demo에서 object storage를 끈다. 기동 rule bean에 주입 멤버가 있으면 모든 프로필에서 기동이 실패한다. 리뷰어가 제안한 "static @Bean 선언 강제"는 문제없는 등록을 막고 @Value 필드는 통과시켜서 버렸다. - 이 수정 전에 move된 파일의 쿼터 차이를 찾는 쿼리와 재계산 SQL을 docs/fileserver/operations.md에 적었다. 위험·한계: lease 뒤 늦게 끝난 첫 시도의 결과는 기록되지 않는다(그 요청도 500). @SystemCaller가 없는 메시지 handler, 주입 멤버가 있는 기동 rule, working-directory 없이 ./gradlew를 부르는 workflow 명령은 파생 서비스에서 새로 실패하거나 세지지 않는다(업그레이드 안내 B-14~16·B-36·B-39). spotbugsTestFixtures는 게이트 밖이고 기준 커밋에서도 실패하며, 새 검사기의 정규식 경고 8건이 더해졌다. 실제 CI runner 실행은 확인하지 못했다(Gitea repo의 Actions가 꺼져 있다). 검증: ci, 두 빌드의 verifyStrictLaneStages --dry-run, mainCheck, :integrationCheck, -p optional-platforms ci integrationCheck performanceCheck, :performanceCheck, :releaseCheck(-PgitRevision), verify-compose-profile-contracts(18 lane) 첫 실행 통과. 쿼터 재계산 SQL은 실 PostgreSQL 16에서 차이 2행 → 0행을 확인했다. Refs: docs/reviews/2026-11-03-rereview/README.md 9·9.1·10절 BREAKING CHANGE: replay-ttl < processing-lease 설정은 기동 실패, ledger release가 claim token을 받는다, HttpBodyReadException(IOException 하위)이 본문 실패를 싣는다, 기동 rule·비밀 목록 bean의 주입 멤버 금지, verifyStrictLaneStages가 workflow 명령의 working-directory로 빌드를 정한다. --- docs/messaging/outbox-inbox.md | 4 +- .../KafkaDeadLetterQuarantineTest.java | 82 +++++++++++++++++++ 2 files changed, 85 insertions(+), 1 deletion(-) create mode 100644 messaging/messaging-spring-boot-starter-kafka/src/test/java/dev/caskeleton/messaging/autoconfigure/KafkaDeadLetterQuarantineTest.java diff --git a/docs/messaging/outbox-inbox.md b/docs/messaging/outbox-inbox.md index 08f1818..1567cc9 100644 --- a/docs/messaging/outbox-inbox.md +++ b/docs/messaging/outbox-inbox.md @@ -154,7 +154,9 @@ consume 계약은 `MessageHandler` 하나다. handler를 bean으로 등록하 실제 왕복·중복 제거·DLQ는 `MessagingKafkaConsumeQualificationTest`(Kafka + PostgreSQL Testcontainers)가 확인한다. 애플리케이션 경로(앱 outbox relay가 발행 → `adapter:inbound:messaging`이 조립한 inbox와 JPA 트랜잭션 → handler)의 중복 전달·실패 재처리는 `InboxRedeliveryIntegrationTest`(lane -`messagingInboxRedeliveryIntegrationTest`)가 확인한다. +`messagingInboxRedeliveryIntegrationTest`)가 확인한다. 애플리케이션 handler가 쓰기 use case를 부르는 방법 +(`@SystemCaller` handler가 `@SystemInvoked` use case를 직접 만든다)은 `docs/manual/09-outbox-events.md` +「소비」 4단계다. ### 복합 키 diff --git a/messaging/messaging-spring-boot-starter-kafka/src/test/java/dev/caskeleton/messaging/autoconfigure/KafkaDeadLetterQuarantineTest.java b/messaging/messaging-spring-boot-starter-kafka/src/test/java/dev/caskeleton/messaging/autoconfigure/KafkaDeadLetterQuarantineTest.java new file mode 100644 index 0000000..35c6d14 --- /dev/null +++ b/messaging/messaging-spring-boot-starter-kafka/src/test/java/dev/caskeleton/messaging/autoconfigure/KafkaDeadLetterQuarantineTest.java @@ -0,0 +1,82 @@ +package dev.caskeleton.messaging.autoconfigure; + +import static org.assertj.core.api.Assertions.assertThat; + +import dev.caskeleton.messaging.api.error.FailureCategory; +import dev.caskeleton.messaging.api.header.ReservedHeaders; +import java.nio.charset.StandardCharsets; +import java.time.Duration; +import java.util.List; +import java.util.stream.StreamSupport; +import org.apache.kafka.clients.consumer.ConsumerRecord; +import org.apache.kafka.clients.producer.MockProducer; +import org.apache.kafka.clients.producer.ProducerRecord; +import org.apache.kafka.common.header.Header; +import org.apache.kafka.common.serialization.ByteArraySerializer; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.EnumSource; + +/** + * The dead-letter copy says which of the two quarantine paths wrote it (review 2026-11-01 06-14, + * re-review round 2 RR-02-16): a record that could not be rebuilt at all and one whose handler + * spent its attempt budget leave different failure-category bytes, so a redrive can tell a message + * that will never decode from one an outage kept failing. + */ +class KafkaDeadLetterQuarantineTest { + + private static final String DEAD_LETTER_TOPIC = "orders.dlq"; + + @ParameterizedTest + @EnumSource( + value = FailureCategory.class, + names = {"DESERIALIZATION", "POISON_MESSAGE"}) + @DisplayName("격리 사본은 원래 header를 지키고 failure-category를 호출자가 준 분류 하나로 쓴다") + void theCopyCarriesTheCategoryTheCallerGaveInPlaceOfAnyEarlierOne(FailureCategory category) { + // given + MockProducer producer = + new MockProducer<>(true, null, new ByteArraySerializer(), new ByteArraySerializer()); + KafkaDeadLetterQuarantine quarantine = + new KafkaDeadLetterQuarantine(producer, DEAD_LETTER_TOPIC, Duration.ofSeconds(1)); + ConsumerRecord record = + new ConsumerRecord<>("orders", 0, 7L, bytes("order-7"), bytes("{\"broken\"")); + record.headers().add("trace-id", bytes("trace-1")); + record.headers().add(ReservedHeaders.FAILURE_CATEGORY, bytes("STALE_FROM_AN_EARLIER_HOP")); + + // when + boolean confirmed = quarantine.quarantine(record, category, new IllegalStateException("x")); + + // then + ProducerRecord copy = producer.history().getFirst(); + assertThat( + List.of( + confirmed, + copy.topic(), + text(copy.value()), + values(copy, "trace-id"), + values(copy, ReservedHeaders.FAILURE_CATEGORY), + values(copy, ReservedHeaders.FAILURE_CODE))) + .containsExactly( + true, + DEAD_LETTER_TOPIC, + "{\"broken\"", + List.of("trace-1"), + List.of(category.name()), + List.of("IllegalStateException")); + } + + private static List values(ProducerRecord record, String header) { + return StreamSupport.stream(record.headers().headers(header).spliterator(), false) + .map(Header::value) + .map(KafkaDeadLetterQuarantineTest::text) + .toList(); + } + + private static byte[] bytes(String value) { + return value.getBytes(StandardCharsets.UTF_8); + } + + private static String text(byte[] value) { + return new String(value, StandardCharsets.UTF_8); + } +} From 99dbf4beacefd1e2748fc38009911599d215905c Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Wed, 4 Nov 2026 08:11:15 +0900 Subject: [PATCH 6/6] =?UTF-8?q?build(quality)!:=20=ED=85=8C=EC=8A=A4?= =?UTF-8?q?=ED=8A=B8=20=EC=BD=94=EB=93=9C=20=EC=A0=95=EC=A0=81=20=EB=B6=84?= =?UTF-8?q?=EC=84=9D=EC=9D=84=20=EA=B2=8C=EC=9D=B4=ED=8A=B8=EC=97=90=20?= =?UTF-8?q?=EB=84=A3=EA=B3=A0=20=EB=B0=9C=EA=B2=AC=EC=9D=84=20=EA=B3=A0?= =?UTF-8?q?=EC=B9=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: qualityCheck는 spotbugsMain만 돈다. main 밖 source set(test, testFixtures, integrationTest, systemTest 등)의 SpotBugs 태스크 111개는 어느 게이트에도 없었고, 돌려 보니 53개가 실패했다(발견 300건). 그중 동시성 테스트 7건은 CountDownLatch.await의 시간 초과를 무시하고 다음 단계로 가서 순서를 확인하지 않은 채 통과했다. 2개는 분석 classpath에 없는 클래스 때문에 분석이 불완전했다. 방법: - leaf마다 testQualityCheck를 두고 main 빌드는 mainCheck, optional 빌드는 ci에 넣었다. PR 게이트에 넣지 않은 것은 테스트 코드가 배포되지 않고 전체 실행이 ci만큼 걸려서다. - 테스트용 제외 목록 config/spotbugs/exclude-test.xml. 패턴 전체 제외는 이유가 모든 테스트 클래스에 성립하는 것만(보안 범주, 내부 상태 노출, 생성자 예외, 반환값 null 역참조, 아키텍처 위반 fixture). 나머지 30건은 클래스·메서드로 좁히고 이유를 달았다. - 24건은 코드로 고쳤다: await 결과 단언, 공유 변수 원자성, 닫지 않은 Statement, SQLException을 삼키던 upsert 테스트, 만료 없는 키에서 NPE가 나던 Redis fake. 쓰는 곳이 없던 web-fileserver 테스트 helper 2개는 지웠다. - 모든 SpotBugs 태스크가 그 source set의 runtime classpath로 분석하고 분석이 불완전하면 실패한다. SpotBugs 플러그인이 나중에 생긴 source set의 태스크를 등록하면서 classpath를 덮어써서 설정을 평가 뒤에 등록한다. 그 자리에 의존성을 더하는 우회는 버렸다. 위험·한계: 파생 서비스는 자기 테스트 코드의 SpotBugs 발견이 mainCheck를 막는다(업그레이드 안내 B-40). mainCheck가 그만큼 길어진다(main 빌드 테스트 태스크 100개). 검증: ci, 두 빌드 verifyStrictLaneStages --dry-run, mainCheck(testQualityCheck 100개 포함, 3분 10초 → 8분 33초), :integrationCheck, -p optional-platforms ci(testQualityCheck 포함) integrationCheck performanceCheck, :performanceCheck, :releaseCheck(-PgitRevision), verify-compose-profile- contracts(18 lane) 첫 실행 통과. 고친 컨테이너 테스트는 클래스별로 따로 실행해 통과. Refs: docs/reviews/2026-11-03-rereview/README.md 14절 BREAKING CHANGE: mainCheck(optional 빌드는 ci)가 테스트 source set의 SpotBugs·FindSecBugs 발견에 실패한다. 고치거나 config/spotbugs/ exclude-test.xml에 이유를 단 좁은 Match를 더한다. --- .../caskeleton/messaging/kafka/KafkaConsumerRegistrarTest.java | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaConsumerRegistrarTest.java b/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaConsumerRegistrarTest.java index edd7769..83c9bde 100644 --- a/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaConsumerRegistrarTest.java +++ b/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaConsumerRegistrarTest.java @@ -844,7 +844,8 @@ class KafkaConsumerRegistrarTest { } private static final class CommitFailingConsumer extends MockConsumer { - private boolean failCommits; + // Set by the test thread, read by whichever thread commits. + private volatile boolean failCommits; CommitFailingConsumer() { super("earliest");