review-followup Wave 3 라운드 3(P21): messaging 플랫폼 — Kafka 소비(MessageHandler 하나), API 정리

- 결정 10: consume 계약을 `MessageHandler<T>` 하나로, starter-kafka가 consumer 조립(handler bean이 있으면 켜짐,
  `app.messaging.enabled=false`로 끔). 오프셋은 handler Success(inbox면 트랜잭션 커밋) 뒤 또는 DLQ 쓰기 확인 뒤에만 커밋,
  auto-commit 금지, `read_committed`, 재시도 소진 → DLQ(없으면 멈춤) — Kafka+PG로 왕복·중복 제거·DLQ 검증
- 미사용 API 타입·Blocking/Reactive/Batch facade·reactor api 노출 삭제, `PublishResult` 정적 factory,
  `MessagingCapabilities` → EnumSet, API leaf 병합(core-api+schema-api, admin-api+admin-runtime), starter god config 분해,
  Kafka broker 설정은 starter-kafka로, 등급 용어 정리
- 결함 수정: Retry 응답이 시도 횟수를 세지 않아 partition 정지(P21-new-1), deliveryAttempt 항상 1(P21-new-2)
- 통합: app-bootstrap `MessagingPublicSurfaceContractTest` 기대값을 P21 변경에 맞춤, starter-kafka에 `api kafka-clients`

검증: ./gradlew check architectureCheck verifyDependencyLocks :app-bootstrap:verifyEnvKeys :app-bootstrap:integrationTest
:sample-portfolio:integrationTest :messaging:messaging-spring-boot-starter:integrationTest
:messaging:messaging-reliability-jdbc-postgresql:integrationTest mainCheck --continue 통과(812 task)

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
donghyeon-ka
2026-09-29 13:29:46 +09:00
co-authored by Claude Opus 5.5
parent 6397f52dc8
commit 763392c8b2
188 changed files with 3405 additions and 4015 deletions
@@ -0,0 +1,30 @@
package dev.caskeleton.messaging.policy;
/**
* The API tier a destination is approved for.
*
* <p>"Tier" names this one thing in the platform: which API surface a destination may use. How far
* an adapter or capability has been proven is a "grade" ({@code CompatibilityMatrix.SupportGrade}),
* the same word the gRPC family uses for its capability and evidence grades. It was {@code
* CapabilityTier}, which put a third meaning on "capability" beside {@code MessagingCapabilities}
* and the gRPC capability grade (S7-#14).
*
* <p>Recorded on the profile so that the tier boundary is enforced by configuration review rather
* than by whichever handler happens to be wired in. An M1 destination that silently accepted a
* manual settlement handler would move the acknowledge-after-success ordering out of the platform
* and into application code.
*/
public enum ApiTier {
/** Typed publish and handler with platform-owned settlement. */
M1,
/**
* Surfaces beyond M1. None ships: the batch, manual-settlement and pause/resume contracts had no
* implementation and were removed (M-9).
*/
M2,
/** Broker-native capabilities exposed as typed interfaces. */
M3
}
@@ -1,21 +0,0 @@
package dev.caskeleton.messaging.policy;
/**
* The API tier a destination is approved for.
*
* <p>Recorded on the profile so that the tier boundary is enforced by configuration review rather
* than by whichever handler happens to be wired in. An M1 destination that silently accepted a
* manual settlement handler would move the acknowledge-after-success ordering out of the platform
* and into application code.
*/
public enum CapabilityTier {
/** Typed publish and handler with platform-owned settlement. */
M1,
/** Batch, manual settlement, pause and resume, delayed delivery, replay request. */
M2,
/** Broker-native capabilities exposed as typed interfaces. */
M3
}
@@ -46,7 +46,11 @@ public final class DefaultRetryDecisionEngine implements RetryDecisionEngine {
if (policy.orderingImpact() == OrderingImpact.PRESERVE
&& profile.isOrdered()
&& context.capabilities().orderedStream()) {
&& context
.capabilities()
.supports(
dev.caskeleton.messaging.api.destination.MessagingCapabilities.Capability
.ORDERED_STREAM)) {
return new RetryDecision.PauseAndRetry(delay);
}
if (policy.mode() == RetryMode.PAUSE_PARTITION) {
@@ -61,7 +65,12 @@ public final class DefaultRetryDecisionEngine implements RetryDecisionEngine {
if (policy.mode() == RetryMode.INLINE || policy.mode() == RetryMode.BLOCKING) {
return new RetryDecision.RetryInline(delay);
}
if (policy.mode() == RetryMode.BROKER_DELAYED && context.capabilities().delayedDelivery()) {
if (policy.mode() == RetryMode.BROKER_DELAYED
&& context
.capabilities()
.supports(
dev.caskeleton.messaging.api.destination.MessagingCapabilities.Capability
.DELAYED_DELIVERY)) {
return new RetryDecision.PublishToRetryDestination(
policy.retryDestination().orElse(profile.name()), delay);
}
@@ -47,7 +47,7 @@ public record DestinationProfile(
RetryPolicy retry,
DeadLetterPolicy deadLetter,
PayloadPolicy payload,
CapabilityTier tier,
ApiTier tier,
boolean production,
boolean keyResolverConfigured,
boolean topologyAutoCreate) {
@@ -62,7 +62,7 @@ public final class DestinationProfileValidator {
throw new IllegalArgumentException(
"ordering scope KEY requires a key resolver for " + profile.name().value());
}
if (profile.tier() == CapabilityTier.M1 && profile.consumer().manualSettlement()) {
if (profile.tier() == ApiTier.M1 && profile.consumer().manualSettlement()) {
throw new IllegalArgumentException(
"an M1 destination cannot configure manual settlement: " + profile.name().value());
}
@@ -188,7 +188,7 @@ final class DestinationProfileFixtures {
RetryPolicy.none(),
DeadLetterPolicy.to(new DestinationName("order-events-dlq")),
PayloadPolicy.defaults(),
CapabilityTier.M1,
ApiTier.M1,
false,
false,
false);
@@ -298,7 +298,7 @@ final class DestinationProfileFixtures {
base.retry(),
base.deadLetter(),
base.payload(),
CapabilityTier.M1,
ApiTier.M1,
base.production(),
base.keyResolverConfigured(),
base.topologyAutoCreate());
@@ -131,12 +131,11 @@ final class RetryContextFixtures {
private RetryContextFixtures() {}
private static final MessagingCapabilities ORDERED_KAFKA =
new MessagingCapabilities(
true, true, true, true, true, true, true, false, true, true, false, true);
MessagingCapabilities.of(
MessagingCapabilities.Capability.ORDERED_STREAM,
MessagingCapabilities.Capability.DEDUPLICATED_PUBLISH);
private static final MessagingCapabilities PLAIN_QUEUE =
new MessagingCapabilities(
true, true, true, false, false, false, false, false, false, false, true, true);
private static final MessagingCapabilities PLAIN_QUEUE = MessagingCapabilities.none();
static DeliveryMetadata delivery(int attempt) {
return new DeliveryMetadata(