Merge pull request 'fix!: 2026-11 성숙도 리뷰 발견을 고치고 재리뷰를 마친다' (#1) from refactor/maturity-review-2026-11 into main
Reviewed-on: donghyeon.kang/clean-architecture-backend-template#1
This commit is contained in:
@@ -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마다
|
||||
|
||||
@@ -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`인 거부뿐이다.
|
||||
|
||||
| 상황 | 결과 |
|
||||
|---|---|
|
||||
|
||||
@@ -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<T>` 하나다. 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단계다.
|
||||
|
||||
### 복합 키
|
||||
|
||||
|
||||
@@ -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`로 선언한다.** 숨긴다고 타입이
|
||||
|
||||
+22
@@ -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<T> {
|
||||
*/
|
||||
MessageDestination<T> destination();
|
||||
|
||||
/**
|
||||
* The schema versions of {@link #destination()}'s message type that its payload class reads.
|
||||
*
|
||||
* <p>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.
|
||||
*
|
||||
* <p>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<SchemaVersion> schemaVersions() {
|
||||
return Set.of(new SchemaVersion(1));
|
||||
}
|
||||
|
||||
/**
|
||||
* Handles one delivery.
|
||||
*
|
||||
|
||||
+8
@@ -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.
|
||||
*
|
||||
* <p>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
|
||||
*/
|
||||
|
||||
@@ -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')
|
||||
|
||||
+3
-1
@@ -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();
|
||||
|
||||
+3
-2
@@ -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;
|
||||
|
||||
+3
-1
@@ -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<byte[], byte[]> producer;
|
||||
private Consumer<byte[], byte[]> consumer;
|
||||
|
||||
+1
-1
@@ -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;
|
||||
|
||||
|
||||
+38
-5
@@ -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());
|
||||
|
||||
+10
-1
@@ -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();
|
||||
|
||||
+25
-3
@@ -19,8 +19,10 @@ import org.apache.kafka.common.errors.UnsupportedVersionException;
|
||||
* <p>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.
|
||||
*
|
||||
* <p>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.
|
||||
*
|
||||
* <p>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.
|
||||
*
|
||||
* <p>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;
|
||||
|
||||
+15
-3
@@ -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.
|
||||
*
|
||||
* <p>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<byte[], byte[]> record, Throwable reason);
|
||||
boolean quarantine(
|
||||
ConsumerRecord<byte[], byte[]> 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() {}
|
||||
}
|
||||
|
||||
+88
-4
@@ -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<FailureCategory> 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<FailureCategory> 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<FailureCategory> 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<byte[], byte[]> {
|
||||
private boolean failCommits;
|
||||
// Set by the test thread, read by whichever thread commits.
|
||||
private volatile boolean failCommits;
|
||||
|
||||
CommitFailingConsumer() {
|
||||
super("earliest");
|
||||
|
||||
+43
@@ -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);
|
||||
}
|
||||
}
|
||||
+69
@@ -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.
|
||||
*
|
||||
* <p>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);
|
||||
}
|
||||
}
|
||||
+1
-1
@@ -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");
|
||||
|
||||
+1
-1
@@ -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");
|
||||
|
||||
+1
-1
@@ -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");
|
||||
|
||||
+7
@@ -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<T> implements MessageHandler<T> {
|
||||
return delegate.destination();
|
||||
}
|
||||
|
||||
@Override
|
||||
public Set<SchemaVersion> schemaVersions() {
|
||||
return delegate.schemaVersions();
|
||||
}
|
||||
|
||||
@Override
|
||||
public CompletionStage<HandleResult> handle(MessageDelivery<T> delivery) {
|
||||
Objects.requireNonNull(delivery, "delivery must not be null");
|
||||
|
||||
+11
-1
@@ -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);
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
+31
@@ -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() {
|
||||
|
||||
+6
-2
@@ -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<byte[], byte[]> record, Throwable reason) {
|
||||
public boolean quarantine(
|
||||
ConsumerRecord<byte[], byte[]> 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()));
|
||||
|
||||
+82
@@ -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<byte[], byte[]> producer =
|
||||
new MockProducer<>(true, null, new ByteArraySerializer(), new ByteArraySerializer());
|
||||
KafkaDeadLetterQuarantine quarantine =
|
||||
new KafkaDeadLetterQuarantine(producer, DEAD_LETTER_TOPIC, Duration.ofSeconds(1));
|
||||
ConsumerRecord<byte[], byte[]> 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<byte[], byte[]> 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<String> values(ProducerRecord<byte[], byte[]> 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);
|
||||
}
|
||||
}
|
||||
+3
-2
@@ -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");
|
||||
|
||||
+2
-1
@@ -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();
|
||||
|
||||
+1
-1
@@ -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";
|
||||
|
||||
|
||||
+52
-1
@@ -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.
|
||||
*
|
||||
* <p>A named holder rather than a bare {@code Map} bean, because {@code Map} is not a neutral
|
||||
* injection type in Spring — a {@code Map<K, V>} 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.
|
||||
*
|
||||
* <p>A deployment registers what it <em>publishes</em> as a bean of this type. What it
|
||||
* <em>consumes</em> 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.
|
||||
*
|
||||
* <p>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<MessageContractKey, Class<?>> byKey) {
|
||||
public static MessageContracts none() {
|
||||
return new MessageContracts(Map.of());
|
||||
}
|
||||
|
||||
/**
|
||||
* These contracts plus every contract the given handlers consume.
|
||||
*
|
||||
* <p>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<? extends MessageHandler<?>> handlers) {
|
||||
Map<MessageContractKey, Class<?>> 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);
|
||||
}
|
||||
}
|
||||
|
||||
+8
-10
@@ -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<Boolean> 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 "
|
||||
|
||||
+1
-1
@@ -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;
|
||||
|
||||
+12
-2
@@ -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.
|
||||
*
|
||||
* <p>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<MessageContracts> contracts) {
|
||||
ObjectProvider<MessageContracts> contracts,
|
||||
ObjectProvider<dev.caskeleton.messaging.api.delivery.MessageHandler<?>> 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()));
|
||||
}
|
||||
|
||||
/**
|
||||
|
||||
+22
@@ -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}).
|
||||
*
|
||||
* <p>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.
|
||||
*
|
||||
|
||||
+14
-4
@@ -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 {
|
||||
*
|
||||
* <p>{@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;
|
||||
}
|
||||
}
|
||||
|
||||
+126
@@ -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 <T> MessageHandler<T> handler(Class<T> payload, Set<SchemaVersion> versions) {
|
||||
return new MessageHandler<>() {
|
||||
@Override
|
||||
public MessageDestination<T> destination() {
|
||||
return new MessageDestination<>(
|
||||
new DestinationName("order-events"), new MessageType("order.created"), payload);
|
||||
}
|
||||
|
||||
@Override
|
||||
public Set<SchemaVersion> schemaVersions() {
|
||||
return versions;
|
||||
}
|
||||
|
||||
@Override
|
||||
public CompletionStage<HandleResult> handle(MessageDelivery<T> delivery) {
|
||||
return CompletableFuture.completedFuture(HandleResult.success());
|
||||
}
|
||||
};
|
||||
}
|
||||
|
||||
private static MessageHandler<String> handler() {
|
||||
return new MessageHandler<>() {
|
||||
@Override
|
||||
|
||||
+68
@@ -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> T inTransaction(java.util.function.Supplier<T> 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;
|
||||
}
|
||||
}
|
||||
}
|
||||
+7
-9
@@ -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();
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user