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:
co-authored by
Claude Opus 5.5
parent
6397f52dc8
commit
763392c8b2
-33
@@ -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);
|
||||
}
|
||||
-27
@@ -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");
|
||||
}
|
||||
}
|
||||
}
|
||||
-45
@@ -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;
|
||||
}
|
||||
}
|
||||
-27
@@ -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);
|
||||
}
|
||||
-29
@@ -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;
|
||||
}
|
||||
Reference in New Issue
Block a user