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
+18
View File
@@ -108,6 +108,24 @@ transactions.inTransaction(() -> {
별도 transaction으로 예약하면 Inbox가 닫으려던 바로 그 창이 다시 열린다.
### 소비와 연결 (소유자 결정 10)
consume 계약은 `MessageHandler<T>` 하나다. handler를 bean으로 등록하면 `messaging-spring-boot-starter-kafka`가
그 handler가 가리키는 destination마다 Kafka consumer를 연다(`app.messaging.enabled=false`면 없다).
- destination profile이 `guarantees.external-side-effect: INBOX_TRANSACTIONAL`이면 platform이 handler를
`InboxMessageHandler`로 감싼다. 예약과 handler의 쓰기가 같은 transaction에서 commit되고, 이미 예약된
message는 handler를 부르지 않고 `Success`로 settle한다. 이 경우 애플리케이션이 `IdempotentConsumer`
bean(inbox repository + transaction runner)을 둬야 하며, 없으면 기동이 실패한다.
- inbox의 consumer 식별자와 Kafka `group.id`는 destination의 `consumer.group`이다. 없으면 기동이 실패한다.
- offset은 handler가 `Success`로 답하고 (inbox destination이면) 그 transaction이 commit된 뒤에만, 또는
DLQ 토픽 기록이 확인된 뒤에만 넘어간다. auto-commit은 쓰지 않는다.
- `Retry`·예외·timeout은 `retry.max-attempts`까지 partition을 멈추고 다시 읽으며, 다 쓰면 DLQ 토픽에
원본 record를 남기고 넘어간다. DLQ가 없는 destination(at-most-once)은 넘어가지 않고 멈춘다.
- `Reject`는 at-most-once destination에서만 버리고, 그 밖에서는 dead letter로 보낸다.
실제 왕복·중복 제거·DLQ는 `MessagingKafkaConsumeQualificationTest`(Kafka + PostgreSQL Testcontainers)가 확인한다.
### 복합 키
`PRIMARY KEY (message_id, consumer_id)`.
+4 -4
View File
@@ -14,9 +14,9 @@ leaf의 정확한 id는 registry에서 읽는다. family는 **디렉터리 이
| Family | 역할 | 허용 framework |
| --- | --- | --- |
| `*-api` (`core-api`, `schema-api`, `policy`, `reliability-api`, `admin-api`, `transport-spi`) | 값 타입, 포트, 정책 계약 | Java stdlib만. Spring/broker SDK/logging framework 금지 |
| `*-api` (`core-api` — `api`·`schema` 패키지, `policy`, `reliability-api`, `transport-spi`) | 값 타입, 포트, 정책 계약 | Java stdlib만. Spring/broker SDK/logging framework 금지 |
| `schema-*` (json/avro/protobuf), `cloudevents` | 인코딩 구현 | 해당 codec 라이브러리만. Spring 금지 |
| `runtime-core`, `security`, `observability`, `admin-runtime`, `reliability` | framework-free 실행 로직 | Micrometer는 `observability`에서만. 나머지는 stdlib |
| `runtime-core`, `security`, `observability`, `admin`(계약 `admin` + 실행 `admin.runtime`), `reliability` | framework-free 실행 로직 | Micrometer는 `observability`에서만. 나머지는 stdlib |
| `kafka` | broker adapter | 해당 broker client. Spring은 client가 곧 Spring인 경우만 |
| `reliability-jdbc-postgresql` | 관계형 신뢰성 adapter (outbox·inbox repository, admin journal) | Spring JDBC / Spring TX. **JPA 아님** — 이름이 곧 계약이다 |
| `spring-boot-starter`, `spring-boot-starter-kafka` | 조립 경계 | Spring Boot autoconfigure. 여기서만 |
@@ -35,7 +35,7 @@ JDBC이고 SQL은 `jsonb` · `FOR UPDATE SKIP LOCKED` · `ON CONFLICT` · `TIMES
- **vendor 타입을 public signature에 노출하면 그 의존성은 `api`로 선언한다.** 숨긴다고 타입이
숨겨지지 않는다 — consumer가 이 모듈이 문서화한 API에 대해 컴파일하지 못하게 만들 뿐이다.
(`kafka-clients`, `cloudevents-api`, `micrometer-core`, `avro`,
`protobuf-java`, `reactor-core`가 이 규칙으로 `api`다.)
`protobuf-java`가 이 규칙으로 `api`다.)
- 반대로 **노출하지 않는 것은 `implementation`으로 낮춘다.** starter가 노출하지 않는 하위 모듈을
`implementation`으로 내린 것이, JSON codec이 `ObjectMapper`를 private으로만 쓰고 Jackson을
`implementation`으로 둔 것이 그 예다.
@@ -72,7 +72,7 @@ qualification/support 상태를 함께 변경한다.
bridge는 exact canonical envelope bytes를 다시 serialize하지 않고, destination/access/admission/runtime
lease/transport/outcome normalization/observation은 platform 중앙 publish path를 그대로 탄다. bridge
package는 `messaging-core-api`와 `messaging-schema-api`만 보며 concrete runtime/transport/Kafka 타입을
package는 `messaging-core-api`만 보며 concrete runtime/transport/Kafka 타입을
직접 보지 않는다.
**MSG-015 cutover는 끝났다(2026-09-28, 소유자 결정 7).** application의 outbox append는 canonical
@@ -1,8 +0,0 @@
plugins {
id 'ca.platform-module'
}
dependencies {
api project(':messaging:messaging-core-api')
api project(':messaging:messaging-policy')
}
@@ -1,84 +0,0 @@
# This is a Gradle generated file for dependency locking.
# Manual edits can break the build and are not advised.
# This file is expected to be part of source control.
com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,testAnnotationProcessor
com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,testAnnotationProcessor
com.github.spotbugs:spotbugs-annotations:4.10.2=spotbugs
com.github.spotbugs:spotbugs:4.10.2=spotbugs
com.github.stephenc.jcip:jcip-annotations:1.0-1=spotbugs
com.google.auto.service:auto-service-annotations:1.0.1=annotationProcessor,testAnnotationProcessor
com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,testAnnotationProcessor
com.google.auto:auto-common:1.2.2=annotationProcessor,testAnnotationProcessor
com.google.code.findbugs:jsr305:3.0.2=checkstyle,spotbugs
com.google.code.gson:gson:2.13.2=spotbugs
com.google.errorprone:error_prone_annotation:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.errorprone:error_prone_annotations:2.41.0=spotbugs
com.google.errorprone:error_prone_annotations:2.47.0=checkstyle
com.google.errorprone:error_prone_annotations:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,testAnnotationProcessor
com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,testAnnotationProcessor
com.google.guava:guava:33.5.0-jre=annotationProcessor,testAnnotationProcessor
com.google.guava:guava:33.6.0-jre=checkstyle
com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,testAnnotationProcessor
com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,testAnnotationProcessor
com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,testAnnotationProcessor
com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0=spotbugsPlugins
com.puppycrawl.tools:checkstyle:13.5.0=checkstyle
commons-beanutils:commons-beanutils:1.11.0=checkstyle
commons-collections:commons-collections:3.2.2=checkstyle
commons-io:commons-io:2.21.0=spotbugs
info.picocli:picocli:4.7.7=checkstyle
io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,testAnnotationProcessor
io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,testAnnotationProcessor
javax.inject:javax.inject:1=annotationProcessor,testAnnotationProcessor
jaxen:jaxen:2.0.6=spotbugs
net.bytebuddy:byte-buddy:1.17.8=testCompileClasspath,testRuntimeClasspath
net.sf.saxon:Saxon-HE:12.9=checkstyle,spotbugs
org.antlr:antlr4-runtime:4.13.2=checkstyle
org.apache.bcel:bcel:6.12.0=spotbugs
org.apache.commons:commons-lang3:3.20.0=checkstyle,spotbugs
org.apache.commons:commons-text:1.15.0=spotbugs
org.apache.commons:commons-text:1.3=checkstyle
org.apache.httpcomponents:httpclient:4.5.13=checkstyle
org.apache.httpcomponents:httpcore:4.4.16=checkstyle
org.apache.logging.log4j:log4j-api:2.25.5=spotbugs
org.apache.logging.log4j:log4j-core:2.25.5=spotbugs
org.apache.maven.doxia:doxia-core:1.12.0=checkstyle
org.apache.maven.doxia:doxia-logging-api:1.12.0=checkstyle
org.apache.maven.doxia:doxia-module-xdoc:1.12.0=checkstyle
org.apache.maven.doxia:doxia-sink-api:1.12.0=checkstyle
org.apache.xbean:xbean-reflect:3.7=checkstyle
org.apiguardian:apiguardian-api:1.1.2=testCompileClasspath
org.assertj:assertj-core:3.27.7=testCompileClasspath,testRuntimeClasspath
org.codehaus.plexus:plexus-classworlds:2.6.0=checkstyle
org.codehaus.plexus:plexus-component-annotations:2.1.0=checkstyle
org.codehaus.plexus:plexus-container-default:2.1.0=checkstyle
org.codehaus.plexus:plexus-utils:3.3.0=checkstyle
org.dom4j:dom4j:2.2.0=spotbugs
org.javassist:javassist:3.28.0-GA=checkstyle
org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,testAnnotationProcessor,testCompileClasspath
org.junit.jupiter:junit-jupiter-api:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.jupiter:junit-jupiter-engine:6.0.3=testRuntimeClasspath
org.junit.jupiter:junit-jupiter-params:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.jupiter:junit-jupiter:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.platform:junit-platform-commons:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.platform:junit-platform-engine:6.0.3=testRuntimeClasspath
org.junit.platform:junit-platform-launcher:6.0.3=testRuntimeClasspath
org.junit:junit-bom:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit:junit-bom:6.1.0=spotbugs
org.mockito:mockito-core:5.20.0=mockitoAgent
org.opentest4j:opentest4j:1.3.0=testCompileClasspath,testRuntimeClasspath
org.ow2.asm:asm-analysis:9.10.1=spotbugs
org.ow2.asm:asm-commons:9.10.1=spotbugs
org.ow2.asm:asm-tree:9.10.1=spotbugs
org.ow2.asm:asm-util:9.10.1=spotbugs
org.ow2.asm:asm:9.10.1=spotbugs
org.pcollections:pcollections:4.0.1=annotationProcessor,testAnnotationProcessor
org.reflections:reflections:0.10.2=checkstyle
org.slf4j:slf4j-api:2.0.18=spotbugs,spotbugsSlf4j
org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j
org.slf4j:slf4j-simple:2.0.18=checkstyle
org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs
empty=compileClasspath,runtimeClasspath
@@ -1,12 +0,0 @@
plugins {
id 'ca.platform-module'
}
dependencies {
api project(':messaging:messaging-core-api')
api project(':messaging:messaging-policy')
api project(':messaging:messaging-admin-api')
api project(':messaging:messaging-transport-spi')
api project(':messaging:messaging-security')
api project(':messaging:messaging-observability')
}
+14
View File
@@ -0,0 +1,14 @@
plugins {
id 'ca.platform-module'
}
// The admin plane: its contract (package `admin`) and the stdlib services that execute it
// (package `admin.runtime`). They were two leaves, and every consumer of the runtime took the
// contract too, so the split added a registry entry without separating anything (S7-#12).
dependencies {
api project(':messaging:messaging-core-api')
// ReplayService records a MessagingAuditEvent internally; no public signature names it, so
// Micrometer does not reach the journal adapters that implement the contract.
implementation project(':messaging:messaging-observability')
}
@@ -4,7 +4,6 @@ plugins {
dependencies {
api project(':messaging:messaging-core-api')
api project(':messaging:messaging-schema-api')
// api, because CloudEventMapper's public signatures return io.cloudevents.CloudEvent.
//
@@ -1,46 +0,0 @@
package dev.caskeleton.messaging.api.delivery;
import dev.caskeleton.messaging.api.destination.DestinationName;
import java.time.Instant;
import java.util.Objects;
import java.util.Optional;
/**
* Batch-wide facts about one delivered batch.
*
* <p>{@code orderingUnit} is what makes a batch safe to hand to an ordered destination. A batch
* drawn from two partitions cannot be settled or retried as a unit without reordering one of them,
* so an ordered destination requires the batch to name exactly one ordering unit and the runtime
* rejects a batch that spans more.
*
* @param destination the logical destination
* @param size the number of deliveries in the batch
* @param orderingUnit the single partition or queue the batch was drawn from, when it has one
* @param settlableAsBatch whether the broker can settle the whole batch in one operation
* @param receivedAt when the consumer assembled the batch
*/
public record BatchDeliveryMetadata(
DestinationName destination,
int size,
Optional<String> orderingUnit,
boolean settlableAsBatch,
Instant receivedAt) {
public BatchDeliveryMetadata {
Objects.requireNonNull(destination, "destination must not be null");
Objects.requireNonNull(orderingUnit, "orderingUnit must not be null");
Objects.requireNonNull(receivedAt, "receivedAt must not be null");
if (size < 1) {
throw new IllegalArgumentException("a delivered batch has at least one delivery");
}
}
/**
* Reports whether this batch may be handed to a destination with strict ordering.
*
* @return true when the batch came from exactly one ordering unit
*/
public boolean isSafeForOrderedDestination() {
return orderingUnit.isPresent();
}
}
@@ -1,29 +0,0 @@
package dev.caskeleton.messaging.api.delivery;
import java.util.List;
import java.util.Objects;
/**
* A batch of decoded messages handed to a batch handler.
*
* @param <T> the payload type
* @param deliveries the individual deliveries, in broker order
* @param metadata batch-wide facts
*/
public record BatchMessageDelivery<T>(
List<MessageDelivery<T>> deliveries, BatchDeliveryMetadata metadata) {
public BatchMessageDelivery {
Objects.requireNonNull(deliveries, "deliveries must not be null");
Objects.requireNonNull(metadata, "metadata must not be null");
deliveries = List.copyOf(deliveries);
if (deliveries.isEmpty()) {
throw new IllegalArgumentException("a delivered batch is never empty");
}
if (deliveries.size() != metadata.size()) {
throw new IllegalArgumentException(
"metadata size %d does not match %d deliveries"
.formatted(metadata.size(), deliveries.size()));
}
}
}
@@ -1,24 +0,0 @@
package dev.caskeleton.messaging.api.delivery;
import java.util.concurrent.CompletionStage;
/**
* The M2 batch consume entry point.
*
* <p>The handler returns one {@link HandleResult} for the whole batch. On a broker that settles
* batches atomically the runtime applies that result once; on a broker that settles per message it
* applies the same result to each delivery. Either way the handler is not asked to reason about
* which settlement mode it is running under.
*
* @param <T> the payload type
*/
public interface BatchMessageHandler<T> {
/**
* Handles one delivered batch.
*
* @param batch the batch to handle
* @return a stage completing with the outcome for the whole batch
*/
CompletionStage<HandleResult> handle(BatchMessageDelivery<T> batch);
}
@@ -1,18 +1,33 @@
package dev.caskeleton.messaging.api.delivery;
import dev.caskeleton.messaging.api.destination.MessageDestination;
import java.util.concurrent.CompletionStage;
/**
* The M1 typed handler implemented by ordinary business code.
* The one consume contract, implemented by ordinary business code.
*
* <p>Handlers state an outcome and never touch broker acknowledgement APIs. Duplicate delivery is a
* normal condition, not an error: implementations are expected to be idempotent, or to sit behind
* the Inbox.
* normal condition, not an error: implementations are expected to be idempotent, or to consume a
* destination whose profile declares {@code INBOX_TRANSACTIONAL}, where the platform runs the
* handler inside the inbox reservation's transaction.
*
* <p>Registering an implementation as a bean is what turns consumption on: the broker starter opens
* a consumer for every destination at least one handler names. There is no second, batch or manual
* settlement contract; the platform settles, after the handler has answered.
*
* @param <T> the payload type
*/
public interface MessageHandler<T> {
/**
* The destination, message type and payload type this handler consumes.
*
* <p>A destination may carry several message types; each type has at most one handler.
*
* @return what this handler consumes
*/
MessageDestination<T> destination();
/**
* Handles one delivery.
*
@@ -1,33 +0,0 @@
package dev.caskeleton.messaging.api.delivery;
import dev.caskeleton.messaging.api.destination.DestinationName;
import java.util.concurrent.CompletionStage;
/**
* The M2 consumer flow-control entry point.
*
* <p>Pausing stops new deliveries; it does not abandon the ones already in flight. A paused
* consumer stays a member of its group and keeps its assignment, which is the point: leaving the
* group to stop consuming would trigger a rebalance and hand the work to another instance that is
* just as overloaded.
*/
public interface PauseResumeController {
/**
* Stops new deliveries for a destination scope.
*
* @param destination the logical destination
* @param scope the partition, queue, or {@code "*"} for every assigned unit
* @return a stage completing once no further deliveries will be dispatched
*/
CompletionStage<Void> pause(DestinationName destination, String scope);
/**
* Resumes deliveries for a destination scope.
*
* @param destination the logical destination
* @param scope the partition, queue, or {@code "*"} for every assigned unit
* @return a stage completing once deliveries may flow again
*/
CompletionStage<Void> resume(DestinationName destination, String scope);
}
@@ -1,11 +0,0 @@
package dev.caskeleton.messaging.api.delivery;
/** How duplicate processing is neutralised once a message has been delivered. */
public enum ProcessingGuarantee {
/** The handler suppresses duplicate effects using the message id or a business key. */
APPLICATION_IDEMPOTENT,
/** Atomicity holds only inside the transaction scope the broker itself defines. */
BROKER_TRANSACTIONAL
}
@@ -1,15 +0,0 @@
package dev.caskeleton.messaging.api.destination;
/** Resolves the capability snapshot for a logical destination. */
public interface CapabilityRegistry {
/**
* Returns the capabilities of a destination.
*
* @param destination the logical destination
* @return the capability snapshot
* @throws dev.caskeleton.messaging.api.error.MessagingConfigurationException when the destination
* is not registered
*/
DestinationCapabilities capabilities(DestinationName destination);
}
@@ -1,5 +1,10 @@
package dev.caskeleton.messaging.api.destination;
import java.util.Collections;
import java.util.EnumSet;
import java.util.Objects;
import java.util.Set;
/**
* What a broker adapter can actually prove or do.
*
@@ -8,32 +13,35 @@ package dev.caskeleton.messaging.api.destination;
* capability exception — rather than quietly degrading, because a silently weakened guarantee is
* indistinguishable from a working one until the incident.
*
* @param brokerAcknowledgement the adapter can prove the broker accepted a publish
* @param replicationOrPersistenceEvidence the adapter can prove replication or persistence
* @param perMessageSettlement individual messages can be settled
* @param batchSettlement batches can be settled as a unit
* @param orderedStream the destination preserves order inside an ordering unit
* @param keyedOrdering order is preserved per key
* @param replay historical messages can be re-read
* @param delayedDelivery delivery can be scheduled for a future instant
* @param brokerTransaction the broker offers a transaction scope
* @param deduplicatedPublish the broker suppresses duplicate publishes of a stable id
* @param nativeDeadLetter the broker provides dead lettering itself
* @param topologyManagement topology can be inspected or created through the adapter
* <p>A set of named capabilities rather than a row of positional booleans. The record used to take
* twelve booleans in a fixed order, and an adapter declared itself with {@code new
* MessagingCapabilities(true, true, …, false, true)} — a line where swapping two arguments changes
* a guarantee and still compiles. Only the capabilities the platform reads are named: a flag
* nothing consults is a promise nobody checks.
*
* @param supported the capabilities the adapter can prove
*/
public record MessagingCapabilities(
boolean brokerAcknowledgement,
boolean replicationOrPersistenceEvidence,
boolean perMessageSettlement,
boolean batchSettlement,
boolean orderedStream,
boolean keyedOrdering,
boolean replay,
boolean delayedDelivery,
boolean brokerTransaction,
boolean deduplicatedPublish,
boolean nativeDeadLetter,
boolean topologyManagement) {
public record MessagingCapabilities(Set<Capability> supported) {
/** One capability the platform consults before relying on it. */
public enum Capability {
/** The destination preserves order inside an ordering unit; required by pause-and-retry. */
ORDERED_STREAM,
/** Delivery can be scheduled for a future instant; required by broker-delayed retry. */
DELAYED_DELIVERY,
/** The broker suppresses duplicate publishes of a stable id; required by publish dedup. */
DEDUPLICATED_PUBLISH
}
public MessagingCapabilities {
Objects.requireNonNull(supported, "supported must not be null");
supported =
Collections.unmodifiableSet(
supported.isEmpty() ? EnumSet.noneOf(Capability.class) : EnumSet.copyOf(supported));
}
/**
* Returns a capability set with nothing enabled.
@@ -41,7 +49,27 @@ public record MessagingCapabilities(
* @return the empty capability set
*/
public static MessagingCapabilities none() {
return new MessagingCapabilities(
false, false, false, false, false, false, false, false, false, false, false, false);
return new MessagingCapabilities(EnumSet.noneOf(Capability.class));
}
/**
* Returns a capability set holding exactly the named capabilities.
*
* @param first the first capability
* @param rest the remaining capabilities
* @return the capability set
*/
public static MessagingCapabilities of(Capability first, Capability... rest) {
return new MessagingCapabilities(EnumSet.of(first, rest));
}
/**
* Reports whether the adapter can prove a capability.
*
* @param capability the capability to look up
* @return true when it is supported
*/
public boolean supports(Capability capability) {
return supported.contains(Objects.requireNonNull(capability, "capability must not be null"));
}
}
@@ -1,49 +0,0 @@
package dev.caskeleton.messaging.api.error;
import java.io.Serial;
import java.util.Optional;
/** Broker authentication failed. */
public class MessageAuthenticationException extends MessagingException {
@Serial private static final long serialVersionUID = 1L;
private static final FailureCategory CATEGORY = FailureCategory.AUTHENTICATION;
/**
* Creates the exception with a stable code and sanitized message.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
*/
public MessageAuthenticationException(String code, String sanitizedMessage) {
super(new FailureDescriptor(CATEGORY, code, false, sanitizedMessage, Optional.empty()));
}
/**
* Creates the exception with an originating cause.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
* @param cause the originating throwable
*/
public MessageAuthenticationException(String code, String sanitizedMessage, Throwable cause) {
super(
new FailureDescriptor(
CATEGORY,
code,
false,
sanitizedMessage,
Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())),
cause);
}
/**
* Creates the exception from an explicit descriptor.
*
* @param failure the sanitized failure description
*/
public MessageAuthenticationException(FailureDescriptor failure) {
super(failure);
}
}
@@ -1,49 +0,0 @@
package dev.caskeleton.messaging.api.error;
import java.io.Serial;
import java.util.Optional;
/** The broker could not be reached. */
public class MessageBrokerUnavailableException extends MessagingException {
@Serial private static final long serialVersionUID = 1L;
private static final FailureCategory CATEGORY = FailureCategory.TRANSIENT_INFRASTRUCTURE;
/**
* Creates the exception with a stable code and sanitized message.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
*/
public MessageBrokerUnavailableException(String code, String sanitizedMessage) {
super(new FailureDescriptor(CATEGORY, code, true, sanitizedMessage, Optional.empty()));
}
/**
* Creates the exception with an originating cause.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
* @param cause the originating throwable
*/
public MessageBrokerUnavailableException(String code, String sanitizedMessage, Throwable cause) {
super(
new FailureDescriptor(
CATEGORY,
code,
true,
sanitizedMessage,
Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())),
cause);
}
/**
* Creates the exception from an explicit descriptor.
*
* @param failure the sanitized failure description
*/
public MessageBrokerUnavailableException(FailureDescriptor failure) {
super(failure);
}
}
@@ -1,49 +0,0 @@
package dev.caskeleton.messaging.api.error;
import java.io.Serial;
import java.util.Optional;
/** The consumer runtime failed while handling a delivery. */
public class MessageConsumerException extends MessagingException {
@Serial private static final long serialVersionUID = 1L;
private static final FailureCategory CATEGORY = FailureCategory.PROCESSING_TRANSIENT;
/**
* Creates the exception with a stable code and sanitized message.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
*/
public MessageConsumerException(String code, String sanitizedMessage) {
super(new FailureDescriptor(CATEGORY, code, true, sanitizedMessage, Optional.empty()));
}
/**
* Creates the exception with an originating cause.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
* @param cause the originating throwable
*/
public MessageConsumerException(String code, String sanitizedMessage, Throwable cause) {
super(
new FailureDescriptor(
CATEGORY,
code,
true,
sanitizedMessage,
Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())),
cause);
}
/**
* Creates the exception from an explicit descriptor.
*
* @param failure the sanitized failure description
*/
public MessageConsumerException(FailureDescriptor failure) {
super(failure);
}
}
@@ -1,54 +0,0 @@
package dev.caskeleton.messaging.api.error;
import java.io.Serial;
import java.util.Optional;
/**
* Publishing to the dead letter destination failed.
*
* <p>The source message stays unsettled. Acknowledging a source whose DLQ publish failed would
* destroy the only remaining copy.
*/
public class MessageDeadLetterException extends MessagingException {
@Serial private static final long serialVersionUID = 1L;
private static final FailureCategory CATEGORY = FailureCategory.TRANSIENT_INFRASTRUCTURE;
/**
* Creates the exception with a stable code and sanitized message.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
*/
public MessageDeadLetterException(String code, String sanitizedMessage) {
super(new FailureDescriptor(CATEGORY, code, true, sanitizedMessage, Optional.empty()));
}
/**
* Creates the exception with an originating cause.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
* @param cause the originating throwable
*/
public MessageDeadLetterException(String code, String sanitizedMessage, Throwable cause) {
super(
new FailureDescriptor(
CATEGORY,
code,
true,
sanitizedMessage,
Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())),
cause);
}
/**
* Creates the exception from an explicit descriptor.
*
* @param failure the sanitized failure description
*/
public MessageDeadLetterException(FailureDescriptor failure) {
super(failure);
}
}
@@ -1,54 +0,0 @@
package dev.caskeleton.messaging.api.error;
import java.io.Serial;
import java.util.Optional;
/**
* The handler exceeded its timeout.
*
* <p>Whether the handler committed a side effect before the deadline is unknown, so the delivery is
* recorded as possibly duplicated when it is retried.
*/
public class MessageHandlerTimeoutException extends MessagingException {
@Serial private static final long serialVersionUID = 1L;
private static final FailureCategory CATEGORY = FailureCategory.PROCESSING_TRANSIENT;
/**
* Creates the exception with a stable code and sanitized message.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
*/
public MessageHandlerTimeoutException(String code, String sanitizedMessage) {
super(new FailureDescriptor(CATEGORY, code, true, sanitizedMessage, Optional.empty()));
}
/**
* Creates the exception with an originating cause.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
* @param cause the originating throwable
*/
public MessageHandlerTimeoutException(String code, String sanitizedMessage, Throwable cause) {
super(
new FailureDescriptor(
CATEGORY,
code,
true,
sanitizedMessage,
Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())),
cause);
}
/**
* Creates the exception from an explicit descriptor.
*
* @param failure the sanitized failure description
*/
public MessageHandlerTimeoutException(FailureDescriptor failure) {
super(failure);
}
}
@@ -1,49 +0,0 @@
package dev.caskeleton.messaging.api.error;
import java.io.Serial;
import java.util.Optional;
/** A header was reserved, secret, or exceeded a limit. */
public class MessageHeaderRejectedException extends MessagingException {
@Serial private static final long serialVersionUID = 1L;
private static final FailureCategory CATEGORY = FailureCategory.PERMANENT_BUSINESS;
/**
* Creates the exception with a stable code and sanitized message.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
*/
public MessageHeaderRejectedException(String code, String sanitizedMessage) {
super(new FailureDescriptor(CATEGORY, code, false, sanitizedMessage, Optional.empty()));
}
/**
* Creates the exception with an originating cause.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
* @param cause the originating throwable
*/
public MessageHeaderRejectedException(String code, String sanitizedMessage, Throwable cause) {
super(
new FailureDescriptor(
CATEGORY,
code,
false,
sanitizedMessage,
Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())),
cause);
}
/**
* Creates the exception from an explicit descriptor.
*
* @param failure the sanitized failure description
*/
public MessageHeaderRejectedException(FailureDescriptor failure) {
super(failure);
}
}
@@ -1,54 +0,0 @@
package dev.caskeleton.messaging.api.error;
import java.io.Serial;
import java.util.Optional;
/**
* The publish outcome could not be determined.
*
* <p>The broker may hold the message. Republishing is permitted only under the same logical message
* id, so that broker deduplication or a downstream Inbox can collapse the duplicate.
*/
public class MessagePublishAmbiguousException extends MessagingException {
@Serial private static final long serialVersionUID = 1L;
private static final FailureCategory CATEGORY = FailureCategory.AMBIGUOUS;
/**
* Creates the exception with a stable code and sanitized message.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
*/
public MessagePublishAmbiguousException(String code, String sanitizedMessage) {
super(new FailureDescriptor(CATEGORY, code, false, sanitizedMessage, Optional.empty()));
}
/**
* Creates the exception with an originating cause.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
* @param cause the originating throwable
*/
public MessagePublishAmbiguousException(String code, String sanitizedMessage, Throwable cause) {
super(
new FailureDescriptor(
CATEGORY,
code,
false,
sanitizedMessage,
Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())),
cause);
}
/**
* Creates the exception from an explicit descriptor.
*
* @param failure the sanitized failure description
*/
public MessagePublishAmbiguousException(FailureDescriptor failure) {
super(failure);
}
}
@@ -1,53 +0,0 @@
package dev.caskeleton.messaging.api.error;
import java.io.Serial;
import java.util.Optional;
/**
* The broker definitively refused the publish.
*
* <p>The message is known not to be stored, so abandoning this attempt is safe.
*/
public class MessagePublishRejectedException extends MessagingException {
@Serial private static final long serialVersionUID = 1L;
private static final FailureCategory CATEGORY = FailureCategory.PERMANENT_BUSINESS;
/**
* Creates the exception with a stable code and sanitized message.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
*/
public MessagePublishRejectedException(String code, String sanitizedMessage) {
super(new FailureDescriptor(CATEGORY, code, false, sanitizedMessage, Optional.empty()));
}
/**
* Creates the exception with an originating cause.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
* @param cause the originating throwable
*/
public MessagePublishRejectedException(String code, String sanitizedMessage, Throwable cause) {
super(
new FailureDescriptor(
CATEGORY,
code,
false,
sanitizedMessage,
Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())),
cause);
}
/**
* Creates the exception from an explicit descriptor.
*
* @param failure the sanitized failure description
*/
public MessagePublishRejectedException(FailureDescriptor failure) {
super(failure);
}
}
@@ -1,49 +0,0 @@
package dev.caskeleton.messaging.api.error;
import java.io.Serial;
import java.util.Optional;
/** A redrive operation failed. */
public class MessageRedriveException extends MessagingException {
@Serial private static final long serialVersionUID = 1L;
private static final FailureCategory CATEGORY = FailureCategory.TRANSIENT_INFRASTRUCTURE;
/**
* Creates the exception with a stable code and sanitized message.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
*/
public MessageRedriveException(String code, String sanitizedMessage) {
super(new FailureDescriptor(CATEGORY, code, true, sanitizedMessage, Optional.empty()));
}
/**
* Creates the exception with an originating cause.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
* @param cause the originating throwable
*/
public MessageRedriveException(String code, String sanitizedMessage, Throwable cause) {
super(
new FailureDescriptor(
CATEGORY,
code,
true,
sanitizedMessage,
Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())),
cause);
}
/**
* Creates the exception from an explicit descriptor.
*
* @param failure the sanitized failure description
*/
public MessageRedriveException(FailureDescriptor failure) {
super(failure);
}
}
@@ -1,49 +0,0 @@
package dev.caskeleton.messaging.api.error;
import java.io.Serial;
import java.util.Optional;
/** The retry policy's attempt budget was exhausted. */
public class MessageRetryExhaustedException extends MessagingException {
@Serial private static final long serialVersionUID = 1L;
private static final FailureCategory CATEGORY = FailureCategory.PERMANENT_BUSINESS;
/**
* Creates the exception with a stable code and sanitized message.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
*/
public MessageRetryExhaustedException(String code, String sanitizedMessage) {
super(new FailureDescriptor(CATEGORY, code, false, sanitizedMessage, Optional.empty()));
}
/**
* Creates the exception with an originating cause.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
* @param cause the originating throwable
*/
public MessageRetryExhaustedException(String code, String sanitizedMessage, Throwable cause) {
super(
new FailureDescriptor(
CATEGORY,
code,
false,
sanitizedMessage,
Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())),
cause);
}
/**
* Creates the exception from an explicit descriptor.
*
* @param failure the sanitized failure description
*/
public MessageRetryExhaustedException(FailureDescriptor failure) {
super(failure);
}
}
@@ -1,49 +0,0 @@
package dev.caskeleton.messaging.api.error;
import java.io.Serial;
import java.util.Optional;
/** The broker accepted the publish but could not route it. */
public class MessageRoutingException extends MessagingException {
@Serial private static final long serialVersionUID = 1L;
private static final FailureCategory CATEGORY = FailureCategory.PERMANENT_BUSINESS;
/**
* Creates the exception with a stable code and sanitized message.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
*/
public MessageRoutingException(String code, String sanitizedMessage) {
super(new FailureDescriptor(CATEGORY, code, false, sanitizedMessage, Optional.empty()));
}
/**
* Creates the exception with an originating cause.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
* @param cause the originating throwable
*/
public MessageRoutingException(String code, String sanitizedMessage, Throwable cause) {
super(
new FailureDescriptor(
CATEGORY,
code,
false,
sanitizedMessage,
Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())),
cause);
}
/**
* Creates the exception from an explicit descriptor.
*
* @param failure the sanitized failure description
*/
public MessageRoutingException(FailureDescriptor failure) {
super(failure);
}
}
@@ -1,49 +0,0 @@
package dev.caskeleton.messaging.api.error;
import java.io.Serial;
import java.util.Optional;
/** Settlement was refused by the broker. */
public class MessageSettlementException extends MessagingException {
@Serial private static final long serialVersionUID = 1L;
private static final FailureCategory CATEGORY = FailureCategory.TRANSIENT_INFRASTRUCTURE;
/**
* Creates the exception with a stable code and sanitized message.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
*/
public MessageSettlementException(String code, String sanitizedMessage) {
super(new FailureDescriptor(CATEGORY, code, true, sanitizedMessage, Optional.empty()));
}
/**
* Creates the exception with an originating cause.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
* @param cause the originating throwable
*/
public MessageSettlementException(String code, String sanitizedMessage, Throwable cause) {
super(
new FailureDescriptor(
CATEGORY,
code,
true,
sanitizedMessage,
Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())),
cause);
}
/**
* Creates the exception from an explicit descriptor.
*
* @param failure the sanitized failure description
*/
public MessageSettlementException(FailureDescriptor failure) {
super(failure);
}
}
@@ -1,53 +0,0 @@
package dev.caskeleton.messaging.api.error;
import java.io.Serial;
import java.util.Optional;
/**
* Settlement was sent but not confirmed.
*
* <p>Redelivery is possible. Callers must not treat this as a successful settlement.
*/
public class MessageSettlementUnknownException extends MessagingException {
@Serial private static final long serialVersionUID = 1L;
private static final FailureCategory CATEGORY = FailureCategory.AMBIGUOUS;
/**
* Creates the exception with a stable code and sanitized message.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
*/
public MessageSettlementUnknownException(String code, String sanitizedMessage) {
super(new FailureDescriptor(CATEGORY, code, false, sanitizedMessage, Optional.empty()));
}
/**
* Creates the exception with an originating cause.
*
* @param code the stable failure code
* @param sanitizedMessage the operator-facing description
* @param cause the originating throwable
*/
public MessageSettlementUnknownException(String code, String sanitizedMessage, Throwable cause) {
super(
new FailureDescriptor(
CATEGORY,
code,
false,
sanitizedMessage,
Optional.ofNullable(cause).map(value -> value.getClass().getSimpleName())),
cause);
}
/**
* Creates the exception from an explicit descriptor.
*
* @param failure the sanitized failure description
*/
public MessageSettlementUnknownException(FailureDescriptor failure) {
super(failure);
}
}
@@ -1,25 +0,0 @@
package dev.caskeleton.messaging.api.publish;
import java.util.List;
import java.util.concurrent.CompletionStage;
/**
* The M2 batch publish entry point.
*
* <p>A batch is a throughput optimisation, not a transaction. Entries succeed, fail, and go
* ambiguous independently, and {@link BatchPublishResult} keeps every entry's outcome against its
* submission index so the caller can act per entry. Nothing here rolls back: an adapter that
* reported a confirmed entry cannot un-publish it because a later entry was rejected.
*/
public interface BatchMessagePublisher {
/**
* Publishes a batch of independent requests.
*
* @param requests the entries to publish, in submission order
* @param options the batch-wide options
* @return a stage completing with one outcome per submitted entry
*/
CompletionStage<BatchPublishResult> publish(
List<PublishRequest<?>> requests, BatchPublishOptions options);
}
@@ -1,27 +0,0 @@
package dev.caskeleton.messaging.api.publish;
import dev.caskeleton.messaging.api.MessageId;
import java.util.Objects;
/**
* One item's outcome inside a batch publish.
*
* <p>Kept per index rather than collapsed into a batch-level success flag. A batch is not a
* transaction: some items confirm, some are rejected, and some are ambiguous, and the caller has to
* be able to act differently on each. A single boolean would force it to re-submit everything,
* which duplicates the items that already landed.
*
* @param index the item's position in the submitted list
* @param messageId the item's logical identity
* @param result the item's outcome and evidence
*/
public record BatchPublishItemResult(int index, MessageId messageId, PublishResult result) {
public BatchPublishItemResult {
Objects.requireNonNull(messageId, "messageId must not be null");
Objects.requireNonNull(result, "result must not be null");
if (index < 0) {
throw new IllegalArgumentException("index must not be negative");
}
}
}
@@ -1,42 +0,0 @@
package dev.caskeleton.messaging.api.publish;
import java.time.Duration;
import java.util.Objects;
/**
* Options covering a whole batch publish.
*
* <p>There is no retry setting. A batch is not a transaction, and retrying the batch would resubmit
* entries that already confirmed, so the platform never retries one on the caller's behalf; the
* caller resubmits the individual entries it knows are duplicate-safe under their original {@code
* messageId}.
*
* @param timeout the deadline for the whole batch
* @param maxBatchSize the largest number of entries accepted in one call
* @param stopOnFirstRejection whether to skip remaining entries once one is rejected
*/
public record BatchPublishOptions(
Duration timeout, int maxBatchSize, boolean stopOnFirstRejection) {
private static final Duration DEFAULT_TIMEOUT = Duration.ofSeconds(30);
private static final int DEFAULT_MAX_BATCH_SIZE = 500;
public BatchPublishOptions {
Objects.requireNonNull(timeout, "timeout must not be null");
if (timeout.isNegative() || timeout.isZero()) {
throw new IllegalArgumentException("batch timeout must be positive");
}
if (maxBatchSize < 1) {
throw new IllegalArgumentException("maxBatchSize must be at least 1");
}
}
/**
* Returns the defaults: thirty seconds, 500 entries, best-effort completion of every entry.
*
* @return the default options
*/
public static BatchPublishOptions defaults() {
return new BatchPublishOptions(DEFAULT_TIMEOUT, DEFAULT_MAX_BATCH_SIZE, false);
}
}
@@ -1,44 +0,0 @@
package dev.caskeleton.messaging.api.publish;
import java.time.Duration;
import java.util.List;
import java.util.Objects;
/**
* The outcome of one batch publish.
*
* <p>There is no automatic batch retry. Re-submitting a whole batch because part of it failed
* duplicates the part that succeeded; the caller re-submits only the items it decides are
* duplicate-safe, under their original message ids.
*
* @param items each item's outcome, in submission order
* @param elapsed how long the batch took
*/
public record BatchPublishResult(List<BatchPublishItemResult> items, Duration elapsed) {
public BatchPublishResult {
Objects.requireNonNull(items, "items must not be null");
Objects.requireNonNull(elapsed, "elapsed must not be null");
items = List.copyOf(items);
}
/**
* Returns the items with a given completion.
*
* @param completion the completion to select
* @return the matching items
*/
public List<BatchPublishItemResult> withCompletion(PublishCompletion completion) {
return items.stream().filter(item -> item.result().completion() == completion).toList();
}
/**
* Reports whether every item confirmed.
*
* @return true when nothing was rejected or ambiguous
*/
public boolean allConfirmed() {
return items.stream()
.allMatch(item -> item.result().completion() == PublishCompletion.CONFIRMED);
}
}
@@ -1,30 +0,0 @@
package dev.caskeleton.messaging.api.publish;
import dev.caskeleton.messaging.api.MessageEnvelope;
import dev.caskeleton.messaging.api.destination.MessageDestination;
/**
* The blocking facade over the asynchronous publisher.
*
* <p>Offered because most business code is written against a blocking data access layer, and
* forcing a {@code CompletionStage} through it produces worse code than a blocking call does. It is
* a facade rather than a second implementation: the core stays asynchronous, and this only converts
* the lifecycle.
*
* <p>It respects the publish deadline rather than waiting indefinitely, so a stalled broker
* surfaces as a timeout with ambiguous evidence instead of an exhausted thread pool.
*/
public interface BlockingMessagePublisher {
/**
* Publishes one message and waits for its outcome.
*
* @param <T> the payload type
* @param destination the logical destination
* @param message the envelope to publish
* @param options per-call options, including the deadline
* @return the outcome and its evidence
*/
<T> PublishResult publish(
MessageDestination<T> destination, MessageEnvelope<T> message, PublishOptions options);
}
@@ -1,28 +0,0 @@
package dev.caskeleton.messaging.api.publish;
import dev.caskeleton.messaging.api.MessageEnvelope;
import dev.caskeleton.messaging.api.destination.MessageDestination;
import java.time.Instant;
import java.util.concurrent.CompletionStage;
/**
* The M2 scheduled-delivery entry point.
*
* <p>Only destinations whose runtime declares {@code delayedDelivery} accept these calls. A plain
* Kafka topic does not: emulating a delay by holding the message in the producer would make the
* publisher's own liveness the schedule, so the platform rejects the call instead of pretending.
*/
public interface DelayedMessagePublisher {
/**
* Publishes a message the broker must not deliver before the given instant.
*
* @param <T> the payload type
* @param destination the logical destination
* @param message the envelope to publish
* @param deliverAt the earliest delivery time
* @return a stage completing with the publish outcome and its evidence
*/
<T> CompletionStage<PublishResult> publish(
MessageDestination<T> destination, MessageEnvelope<T> message, Instant deliverAt);
}
@@ -100,6 +100,70 @@ public record PublishResult(
}
}
/**
* A publish the broker confirmed.
*
* @param level the confirmation the broker supplied
* @param routing whether the broker routed it; a broker with no routing step reports {@link
* RoutingOutcome#NOT_APPLICABLE}
* @param position the broker coordinate, when the broker reported one
* @param elapsed wall-clock time spent
* @return the confirmed result
*/
public static PublishResult confirmed(
ConfirmationLevel level,
RoutingOutcome routing,
Optional<BrokerPosition> position,
Duration elapsed) {
return new PublishResult(
PublishCompletion.CONFIRMED,
PublishEvidence.confirmed(level),
routing,
position,
1,
elapsed,
Optional.empty());
}
/**
* A publish refused before anything left the process.
*
* <p>Routing is {@link RoutingOutcome#NOT_APPLICABLE}: nothing reached a broker that could have
* routed it.
*
* @param elapsed wall-clock time spent
* @param failure why it was refused
* @return the rejected result
*/
public static PublishResult rejected(Duration elapsed, FailureDescriptor failure) {
return new PublishResult(
PublishCompletion.REJECTED,
PublishEvidence.notTransmitted(),
RoutingOutcome.NOT_APPLICABLE,
Optional.empty(),
1,
elapsed,
Optional.of(failure));
}
/**
* A publish whose fate is unknown: the broker may or may not hold the message.
*
* @param elapsed wall-clock time spent
* @param failure what made the outcome unknowable
* @return the ambiguous result
*/
public static PublishResult ambiguous(Duration elapsed, FailureDescriptor failure) {
return new PublishResult(
PublishCompletion.AMBIGUOUS,
PublishEvidence.ambiguous(),
RoutingOutcome.UNKNOWN,
Optional.empty(),
1,
elapsed,
Optional.of(failure));
}
/**
* Reports whether the broker may be holding this message.
*
@@ -1,25 +0,0 @@
package dev.caskeleton.messaging.api.settlement;
import dev.caskeleton.messaging.api.delivery.MessageDelivery;
import java.util.concurrent.CompletionStage;
/**
* The M2 handler that settles its own deliveries.
*
* <p>Available only to modules granted the advanced capability. A handler that returns without
* calling a terminal settlement method is a defect the runtime detects and reports rather than
* silently leaving the message in flight.
*
* @param <T> the payload type
*/
public interface ManualMessageHandler<T> {
/**
* Handles one delivery, settling it through the supplied controller.
*
* @param delivery the decoded message and its metadata
* @param settlement the settlement handle for this delivery
* @return a stage completing when handling has finished
*/
CompletionStage<Void> handle(MessageDelivery<T> delivery, SettlementController settlement);
}
@@ -1,50 +0,0 @@
package dev.caskeleton.messaging.api.settlement;
import dev.caskeleton.messaging.api.error.FailureDescriptor;
import java.time.Duration;
import java.util.concurrent.CompletionStage;
/**
* The M2 manual settlement handle.
*
* <p>No method here accepts a broker channel, delivery tag, or offset. Manual settlement changes
* <em>when</em> the platform settles, never <em>who</em> settles, so the same DLQ-before-ack
* ordering and payload limits still apply.
*
* <p>Exactly one terminal call is permitted per delivery; a second call fails rather than racing
* the first.
*/
public interface SettlementController {
/**
* Acknowledges the message.
*
* @return a stage completing with the settlement outcome
*/
CompletionStage<SettlementResult> ack();
/**
* Schedules the message for another attempt.
*
* @param delay how long to wait before redelivery
* @return a stage completing with the settlement outcome
*/
CompletionStage<SettlementResult> retry(Duration delay);
/**
* Routes the message to the dead letter destination, settling the source only after that publish
* is confirmed.
*
* @param failure the sanitized failure description
* @return a stage completing with the settlement outcome
*/
CompletionStage<SettlementResult> deadLetter(FailureDescriptor failure);
/**
* Discards the message without dead lettering.
*
* @param failure the sanitized failure description
* @return a stage completing with the settlement outcome
*/
CompletionStage<SettlementResult> reject(FailureDescriptor failure);
}
@@ -31,9 +31,24 @@ class DestinationCapabilityTest {
void emptyCapabilitySetAdvertisesNothing() {
MessagingCapabilities capabilities = MessagingCapabilities.none();
assertThat(capabilities.brokerAcknowledgement()).isFalse();
assertThat(capabilities.replay()).isFalse();
assertThat(capabilities.brokerTransaction()).isFalse();
assertThat(capabilities.supported()).isEmpty();
}
@Test
@org.junit.jupiter.api.DisplayName("이름 붙인 capability만 지원하고 넘긴 집합을 나중에 바꿔도 영향이 없다")
void aCapabilitySetSupportsExactlyWhatWasNamedAndIgnoresLaterChangesToTheInput() {
// given
java.util.Set<MessagingCapabilities.Capability> input =
java.util.EnumSet.of(MessagingCapabilities.Capability.ORDERED_STREAM);
MessagingCapabilities capabilities = new MessagingCapabilities(input);
// when
input.add(MessagingCapabilities.Capability.DEDUPLICATED_PUBLISH);
// then
assertThat(capabilities.supports(MessagingCapabilities.Capability.ORDERED_STREAM)).isTrue();
assertThat(capabilities.supports(MessagingCapabilities.Capability.DEDUPLICATED_PUBLISH))
.isFalse();
}
@Test
@@ -7,6 +7,7 @@ import dev.caskeleton.messaging.api.error.FailureCategory;
import dev.caskeleton.messaging.api.error.FailureDescriptor;
import java.time.Duration;
import java.util.Optional;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
class PublishResultTest {
@@ -239,4 +240,47 @@ class PublishResultTest {
Optional.empty()))
.isInstanceOf(IllegalArgumentException.class);
}
@Test
@DisplayName("거부 factory는 전송되지 않았고 라우팅 대상이 아닌 결과를 만든다")
void theRejectedFactoryReportsNothingWasTransmittedOrRouted() {
// when
PublishResult result = PublishResult.rejected(Duration.ofMillis(3), AMBIGUOUS_FAILURE);
// then
assertThat(result.completion()).isEqualTo(PublishCompletion.REJECTED);
assertThat(result.evidence()).isEqualTo(PublishEvidence.notTransmitted());
assertThat(result.routingOutcome()).isEqualTo(RoutingOutcome.NOT_APPLICABLE);
assertThat(result.failure()).contains(AMBIGUOUS_FAILURE);
}
@Test
@DisplayName("모호 factory는 브로커가 메시지를 가졌을 수 있다고 보고한다")
void theAmbiguousFactoryReportsTheBrokerMayHoldTheMessage() {
// when
PublishResult result = PublishResult.ambiguous(Duration.ofMillis(3), AMBIGUOUS_FAILURE);
// then
assertThat(result.mayHaveBeenStored()).isTrue();
assertThat(result.evidence()).isEqualTo(PublishEvidence.ambiguous());
assertThat(result.routingOutcome()).isEqualTo(RoutingOutcome.UNKNOWN);
}
@Test
@DisplayName("확인 factory는 브로커 수락과 위치를 담고 실패 설명은 없다")
void theConfirmedFactoryCarriesAcceptanceAndPositionWithoutAFailure() {
// when
PublishResult result =
PublishResult.confirmed(
ConfirmationLevel.BROKER_ACK,
RoutingOutcome.NOT_APPLICABLE,
Optional.of(POSITION),
Duration.ofMillis(3));
// then
assertThat(result.completion()).isEqualTo(PublishCompletion.CONFIRMED);
assertThat(result.evidence().brokerAccepted()).isTrue();
assertThat(result.position()).contains(POSITION);
assertThat(result.failure()).isEmpty();
}
}
+1 -6
View File
@@ -21,12 +21,11 @@ dependencies {
// `org.apache.kafka` producer API directly, and a declared library that no source names is a
// resolution, a lock entry and a transitive surface bought for nothing.
api project(':messaging:messaging-core-api')
api project(':messaging:messaging-schema-api')
api project(':messaging:messaging-policy')
api project(':messaging:messaging-transport-spi')
api project(':messaging:messaging-observability')
api project(':messaging:messaging-security')
api project(':messaging:messaging-admin-api')
api project(':messaging:messaging-admin')
// api: the public constructors and mappers take and return Producer, ProducerRecord and
// RecordMetadata. Hiding the dependency does not hide the types — it only stops a consumer
@@ -38,10 +37,6 @@ dependencies {
testImplementation project(':messaging:messaging-testkit')
testFixturesImplementation project(':messaging:messaging-testkit')
// Test-only. The topology validator is broker-neutral, so it lives in the admin runtime; the
// live-broker suite is here because only this module has a Kafka container to describe.
testImplementation project(':messaging:messaging-admin-runtime')
// Live-broker certification. The deterministic suite proves the platform's semantics; these
// prove the client actually behaves that way against the version the matrix claims.
integrationTestImplementation 'org.testcontainers:testcontainers-junit-jupiter'

Some files were not shown because too many files have changed in this diff Show More