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
@@ -1,33 +0,0 @@
package dev.caskeleton.messaging.reliability;
import dev.caskeleton.messaging.api.delivery.HandleResult;
import dev.caskeleton.messaging.api.delivery.MessageDelivery;
import java.util.concurrent.CompletionStage;
/**
* Runs a side effect at most once per consumer, whatever the broker redelivers.
*
* <p>{@code consumerName} is a parameter rather than a property of the message because the same
* message legitimately reaches several independent consumers, and each of them is entitled to apply
* its own effect once. Keying the inbox on the message id alone would let whichever consumer ran
* first suppress all the others.
*
* <p>A duplicate is not a failure. The handler returns success for a message it has already
* applied, so the broker settles it and stops redelivering; treating it as an error would park a
* message whose work is already done.
*
* @param <T> the payload type
*/
public interface IdempotentMessageHandler<T> {
/**
* Applies an action once for a given consumer.
*
* @param consumerName the consumer identity the reservation is keyed on
* @param delivery the message being handled
* @param action the effect to apply inside the reservation's transaction
* @return a stage completing with the handler outcome
*/
CompletionStage<HandleResult> handleOnce(
String consumerName, MessageDelivery<T> delivery, TransactionalMessageAction<T> action);
}
@@ -1,27 +0,0 @@
package dev.caskeleton.messaging.reliability;
import dev.caskeleton.messaging.api.MessageId;
import java.time.Instant;
import java.util.Objects;
/**
* One row of the consumer inbox.
*
* <p>Keyed by message id <em>and</em> consumer id, because two independent consumers of the same
* event must each process it once — deduplicating on the message alone would let the first consumer
* suppress the second.
*
* @param messageId the logical message identity
* @param consumerId the consumer's stable identity
* @param processedAt when the side effect committed
*/
public record InboxRecord(MessageId messageId, String consumerId, Instant processedAt) {
public InboxRecord {
Objects.requireNonNull(messageId, "messageId must not be null");
Objects.requireNonNull(processedAt, "processedAt must not be null");
if (consumerId == null || consumerId.isBlank()) {
throw new IllegalArgumentException("consumerId must not be blank");
}
}
}
@@ -1,45 +0,0 @@
package dev.caskeleton.messaging.reliability;
/**
* What the inbox decided about one delivery.
*
* <p>Three outcomes, not two. Collapsing {@link #ALREADY_APPLIED} and {@link #CLAIMED_ELSEWHERE}
* into a single "duplicate" would settle a message whose effect is still only half-written by
* another instance: if that instance then rolls back, the effect is lost and the broker will never
* redeliver, because this instance already acknowledged it.
*/
public enum InboxResult {
/** No reservation existed; the effect ran inside this transaction. */
APPLIED(true),
/**
* A committed reservation already exists, so the effect ran before.
*
* <p>Settle the message: the work is done and redelivering it achieves nothing.
*/
ALREADY_APPLIED(true),
/**
* Another instance holds an uncommitted reservation for this message.
*
* <p>Do <em>not</em> settle. The other transaction may still roll back, and this delivery is the
* only remaining copy that could re-apply the effect.
*/
CLAIMED_ELSEWHERE(false);
private final boolean safeToSettle;
InboxResult(boolean safeToSettle) {
this.safeToSettle = safeToSettle;
}
/**
* Reports whether the source message may be settled on this outcome.
*
* @return true when settling cannot lose the effect
*/
public boolean isSafeToSettle() {
return safeToSettle;
}
}
@@ -1,27 +0,0 @@
package dev.caskeleton.messaging.reliability;
import dev.caskeleton.messaging.api.MessageEnvelope;
import dev.caskeleton.messaging.api.destination.MessageDestination;
/**
* Enrols a message in the caller's database transaction instead of publishing it.
*
* <p>The return type is {@code void}, and that is the contract. There is no publish outcome to
* report yet: the row is written inside the caller's transaction, so if the transaction rolls back
* the message never existed, and if it commits the relay will publish it later. Handing back a
* {@code PublishResult} here would be a lie about work that has not happened.
*
* <p>This is the answer to the dual-write problem. Writing to the database and publishing to the
* broker in the same method cannot be made atomic; writing both to the database can.
*/
public interface ReliableMessagePublisher {
/**
* Stages a message for publication when the current transaction commits.
*
* @param <T> the payload type
* @param destination the logical destination
* @param message the envelope to publish, carrying the identity the relay will preserve
*/
<T> void addToOutbox(MessageDestination<T> destination, MessageEnvelope<T> message);
}
@@ -1,29 +0,0 @@
package dev.caskeleton.messaging.reliability;
import dev.caskeleton.messaging.api.delivery.MessageDelivery;
/**
* The business work that runs inside the same transaction as the inbox reservation.
*
* <p>Sharing one transaction is the entire mechanism. If the effect committed separately from the
* "I have handled this message" marker, a crash between the two would either replay the effect or
* suppress a message that was never handled — and which of those you get would depend on the order
* the two commits happened to be written in.
*
* <p>Implementations must not settle the message, publish, or start their own transaction. The
* runtime owns the transaction boundary precisely so that the action cannot accidentally commit
* half of it.
*
* @param <T> the payload type
*/
@FunctionalInterface
public interface TransactionalMessageAction<T> {
/**
* Applies the side effect for one delivery.
*
* @param delivery the message being handled
* @throws Exception when the effect fails, rolling back both it and the inbox reservation
*/
void apply(MessageDelivery<T> delivery) throws Exception;
}