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/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/docs/messaging/outbox-inbox.md b/docs/messaging/outbox-inbox.md index bf68398..1567cc9 100644 --- a/docs/messaging/outbox-inbox.md +++ b/docs/messaging/outbox-inbox.md @@ -1,5 +1,32 @@ # 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는 두 +> bean이 있을 때 `IdempotentConsumer`를 만들어 `INBOX_TRANSACTIONAL` destination의 handler를 감싼다. +> 그 leaf는 inbox 마이그레이션(`V1101`)만 자기 history 표로 적용하므로, 아래 "location 추가"는 platform +> outbox를 쓰는 배포의 이야기다. payload decode 목록은 handler bean의 선언으로 만든다. + ## 두 패턴이 각각 무엇을 해결하는가 | 패턴 | 해결하는 문제 | 해결하지 않는 문제 | @@ -125,6 +152,11 @@ 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`)가 확인한다. 애플리케이션 handler가 쓰기 use case를 부르는 방법 +(`@SystemCaller` handler가 `@SystemInvoked` use case를 직접 만든다)은 `docs/manual/09-outbox-events.md` +「소비」 4단계다. ### 복합 키 diff --git a/messaging/CLAUDE.md b/messaging/CLAUDE.md index 14c58e8..931c282 100644 --- a/messaging/CLAUDE.md +++ b/messaging/CLAUDE.md @@ -30,6 +30,41 @@ 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`의 정본과 같은 규칙인지 함께 본다. + +### 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/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-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/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-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/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..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 @@ -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,25 @@ 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 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; + } + private static FailureCategory rejectionCategory(Throwable cause) { if (cause instanceof AuthenticationException) { return FailureCategory.AUTHENTICATION; 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..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 @@ -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() { @@ -761,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"); 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-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-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-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..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 @@ -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 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() { 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-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); + } +} 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/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/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..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,6 +29,13 @@ import org.springframework.context.SmartLifecycle; */ public final class MessagingShutdownLifecycle implements SmartLifecycle { + /** + * 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); @@ -111,14 +118,17 @@ 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. 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 + * @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/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 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(); } }