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,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);
}
@@ -0,0 +1,114 @@
package dev.caskeleton.messaging.schema;
import dev.caskeleton.messaging.api.error.MessageTooLargeException;
import java.io.ByteArrayOutputStream;
import java.io.OutputStream;
import java.util.Objects;
/**
* A byte sink that refuses the byte after the limit instead of the buffer after the fact.
*
* <p>Every codec here used to serialize into an unbounded buffer and compare {@code bytes.length}
* to the configured maximum afterwards. That makes the maximum a reporting threshold rather than an
* allocation bound: a payload whose graph expands to hundreds of megabytes exhausts the heap while
* being written, and the check that would have rejected it never runs. Under a broker consumer that
* is a process-wide outage caused by one message.
*
* <p>This sink fails on the write that would cross the limit, so peak allocation is bounded by the
* limit itself plus whatever the encoder buffers. The exception is the same {@link
* MessageTooLargeException} the after-the-fact check raised, carrying the codec's own error code,
* so callers and evidence records see no behavioural difference for payloads that merely exceed the
* bound.
*
* <p>Not thread-safe, and not meant to be: an instance belongs to a single encode call.
*/
public final class BoundedByteSink extends OutputStream {
private final int maxBytes;
private final String errorCode;
private final ByteArrayOutputStream buffer;
private int written;
private BoundedByteSink(int maxBytes, String errorCode) {
if (maxBytes < 1) {
throw new IllegalArgumentException("maxBytes must be positive");
}
this.maxBytes = maxBytes;
this.errorCode = Objects.requireNonNull(errorCode, "errorCode must not be null");
// Sized to the limit only when the limit is small: a 1 GiB bound must not pre-allocate 1 GiB.
this.buffer = new ByteArrayOutputStream(Math.min(maxBytes, 8_192));
}
/**
* Creates a sink that refuses to accumulate more than {@code maxBytes}.
*
* @param maxBytes the inclusive byte limit
* @param errorCode the code the codec reports for an oversized payload
* @return a bounded sink
*/
public static BoundedByteSink of(int maxBytes, String errorCode) {
return new BoundedByteSink(maxBytes, errorCode);
}
@Override
public void write(int b) {
reserve(1);
buffer.write(b);
}
@Override
public void write(byte[] bytes, int offset, int length) {
Objects.checkFromIndexSize(offset, length, bytes.length);
reserve(length);
buffer.write(bytes, offset, length);
}
/**
* Checks a size the caller can compute before serializing, without consuming the budget.
*
* <p>Protobuf knows its serialized size exactly, so the whole encode can be refused before the
* first byte is written. The subsequent writes are still bounded — this is a cheaper refusal, not
* a replacement for the bound.
*
* @param size the number of bytes the caller is about to produce
*/
public void requireFits(int size) {
if (size < 0) {
throw new IllegalArgumentException("size must not be negative");
}
refuseIfBeyondLimit(size);
}
private void reserve(int size) {
refuseIfBeyondLimit(size);
written += size;
}
private void refuseIfBeyondLimit(int size) {
if (size > maxBytes - written) {
throw new MessageTooLargeException(
errorCode,
("the encoded payload exceeds the %d byte limit; it was refused at byte %d rather than"
+ " buffered in full")
.formatted(maxBytes, written + size));
}
}
/**
* The bytes accumulated so far.
*
* @return a copy of the buffered bytes
*/
public byte[] toByteArray() {
return buffer.toByteArray();
}
/**
* How many bytes have been admitted.
*
* @return the running total
*/
public int written() {
return written;
}
}
@@ -0,0 +1,66 @@
package dev.caskeleton.messaging.schema;
import dev.caskeleton.messaging.api.ContentType;
import java.util.Arrays;
import java.util.Objects;
import java.util.Optional;
/**
* An encoded payload together with the facts needed to decode it again.
*
* <p>The byte array is defensively copied on both construction and access. These bytes travel
* through retry, DLQ, and redrive paths where a shared mutable array would let one stage corrupt
* another's copy of the same logical message.
*
* @param bytes the encoded payload
* @param contentType the codec media type
* @param schemaReference the schema the payload was written against
*/
@SuppressWarnings("ArrayRecordComponent")
public record EncodedMessage(
byte[] bytes, ContentType contentType, Optional<SchemaReference> schemaReference) {
public EncodedMessage {
Objects.requireNonNull(bytes, "encoded bytes must not be null");
Objects.requireNonNull(contentType, "contentType must not be null");
Objects.requireNonNull(schemaReference, "schemaReference must not be null");
bytes = bytes.clone();
}
/**
* Returns a copy of the encoded bytes.
*
* @return the payload bytes
*/
@Override
public byte[] bytes() {
return bytes.clone();
}
/**
* Returns the encoded size without copying.
*
* @return the payload length in bytes
*/
public int size() {
return bytes.length;
}
@Override
public boolean equals(Object other) {
return other instanceof EncodedMessage message
&& Arrays.equals(bytes, message.bytes)
&& contentType.equals(message.contentType)
&& schemaReference.equals(message.schemaReference);
}
@Override
public int hashCode() {
return Objects.hash(Arrays.hashCode(bytes), contentType, schemaReference);
}
@Override
public String toString() {
return "EncodedMessage[contentType=" + contentType.value() + ", size=" + bytes.length + "]";
}
}
@@ -0,0 +1,24 @@
package dev.caskeleton.messaging.schema;
import dev.caskeleton.messaging.api.MessageEnvelope;
import dev.caskeleton.messaging.api.destination.MessageDestination;
import dev.caskeleton.messaging.api.publish.PublishOptions;
import dev.caskeleton.messaging.api.publish.PublishResult;
import java.util.concurrent.CompletionStage;
/**
* Publishes an envelope whose payload has already been encoded by an authoritative application
* contract boundary.
*
* <p>This is intentionally narrower than the transport SPI. Callers may skip only the codec step;
* destination resolution, access policy, admission, runtime leasing, transport normalization and
* observation remain owned by the platform's central publisher.
*/
@FunctionalInterface
public interface EncodedMessagePublisher {
CompletionStage<PublishResult> publishEncoded(
MessageDestination<EncodedMessage> destination,
MessageEnvelope<EncodedMessage> message,
PublishOptions options);
}
@@ -0,0 +1,59 @@
package dev.caskeleton.messaging.schema;
import dev.caskeleton.messaging.api.ContentType;
import dev.caskeleton.messaging.api.MessageType;
import dev.caskeleton.messaging.api.SchemaVersion;
/**
* Encodes and decodes payloads for a single wire format.
*
* <p>Implementations operate against a closed message-type registry. Accepting an unregistered type
* would let a producer introduce a wire contract nothing has reviewed, which is the same class of
* problem that makes Java serialization unsupported here.
*/
public interface MessageCodec {
/**
* Returns the media type this codec produces.
*
* @return the content type
*/
ContentType contentType();
/**
* Encodes a payload.
*
* @param type the catalog message type
* @param version the schema revision
* @param payload the payload to encode
* @return the encoded message
*/
EncodedMessage encode(MessageType type, SchemaVersion version, Object payload);
/**
* Decodes a payload from raw bytes.
*
* @param <T> the payload type
* @param type the catalog message type
* @param version the schema revision
* @param encoded the encoded bytes
* @param payloadType the expected payload class
* @return the decoded payload
*/
<T> T decode(MessageType type, SchemaVersion version, byte[] encoded, Class<T> payloadType);
/**
* Decodes a payload from an encoded message.
*
* @param <T> the payload type
* @param type the catalog message type
* @param version the schema revision
* @param encoded the encoded message
* @param payloadType the expected payload class
* @return the decoded payload
*/
default <T> T decode(
MessageType type, SchemaVersion version, EncodedMessage encoded, Class<T> payloadType) {
return decode(type, version, encoded.bytes(), payloadType);
}
}
@@ -0,0 +1,26 @@
package dev.caskeleton.messaging.schema;
import dev.caskeleton.messaging.api.ContentType;
import java.util.Optional;
/** Resolves the codec for a content type. */
public interface MessageCodecRegistry {
/**
* Returns the codec for a content type.
*
* @param contentType the media type
* @return the codec when registered
*/
Optional<MessageCodec> find(ContentType contentType);
/**
* Returns the Stable default codec.
*
* <p>The raw bytes codec is never eligible: selecting it by default would silently disable schema
* validation for every destination that forgot to declare one.
*
* @return the default codec
*/
MessageCodec defaultCodec();
}
@@ -0,0 +1,49 @@
package dev.caskeleton.messaging.schema;
import dev.caskeleton.messaging.api.MessageType;
import dev.caskeleton.messaging.api.SchemaVersion;
import java.util.Objects;
/**
* The identity a codec registry is keyed on: a message type at a specific schema version.
*
* <p>Keying on the message type alone is what let an unregistered version decode. The version
* travels in the envelope and in {@link SchemaReference}, so a consumer receiving {@code
* order.created v999} would look up {@code order.created}, find the v1 class or parser, decode
* against it, and then keep the v999 label on the result. Nothing failed, and every downstream
* compatibility gate and audit record then described a version that was never registered.
*
* <p>With the version in the key that lookup misses, which is the only honest outcome: the platform
* has no contract for that version and must say so rather than guess one.
*
* @param type the catalog message type
* @param version the schema version the contract is registered for
*/
public record MessageContractKey(MessageType type, SchemaVersion version) {
/** Validates both components. */
public MessageContractKey {
Objects.requireNonNull(type, "messageType must not be null");
Objects.requireNonNull(version, "schemaVersion must not be null");
}
/**
* Creates a key from raw components.
*
* @param type the catalog message type
* @param version the schema version
* @return the key
*/
public static MessageContractKey of(String type, int version) {
return new MessageContractKey(new MessageType(type), new SchemaVersion(version));
}
/**
* Renders the key the way error messages and audit records name a contract.
*
* @return for example {@code order.created v1}
*/
public String describe() {
return type.value() + " v" + version.value();
}
}
@@ -0,0 +1,76 @@
package dev.caskeleton.messaging.schema;
import dev.caskeleton.messaging.api.ContentType;
import dev.caskeleton.messaging.api.MessageType;
import dev.caskeleton.messaging.api.SchemaVersion;
import dev.caskeleton.messaging.api.error.MessageSerializationException;
import dev.caskeleton.messaging.api.error.MessageTooLargeException;
import java.util.Objects;
import java.util.Optional;
/**
* The M2 escape hatch for payloads that carry no schema.
*
* <p>It still enforces the byte limit, and it is deliberately excluded from default codec
* selection: schema-free publishing has to be an explicit, auditable choice per destination, never
* something a destination falls back to because its codec was misconfigured.
*/
public final class RawBytesMessageCodec implements MessageCodec {
/** The default encoded byte limit shared with the Stable codecs. */
public static final int DEFAULT_MAX_BYTES = 1_048_576;
private final int maxBytes;
/** Creates a codec with the default one mebibyte limit. */
public RawBytesMessageCodec() {
this(DEFAULT_MAX_BYTES);
}
/**
* Creates a codec with an explicit byte limit.
*
* @param maxBytes the maximum encoded size
*/
public RawBytesMessageCodec(int maxBytes) {
if (maxBytes < 1) {
throw new IllegalArgumentException("maxBytes must be positive");
}
this.maxBytes = maxBytes;
}
@Override
public ContentType contentType() {
return ContentType.OCTET_STREAM;
}
@Override
public EncodedMessage encode(MessageType type, SchemaVersion version, Object payload) {
Objects.requireNonNull(type, "messageType must not be null");
Objects.requireNonNull(version, "schemaVersion must not be null");
if (!(payload instanceof byte[] bytes)) {
throw new MessageSerializationException(
"RAW_BYTES_PAYLOAD_REQUIRED", "raw bytes codec accepts only byte[] payloads");
}
if (bytes.length > maxBytes) {
throw new MessageTooLargeException(
"RAW_BYTES_TOO_LARGE", "encoded payload exceeds " + maxBytes + " bytes");
}
return new EncodedMessage(bytes, ContentType.OCTET_STREAM, Optional.empty());
}
@Override
public <T> T decode(
MessageType type, SchemaVersion version, byte[] encoded, Class<T> payloadType) {
Objects.requireNonNull(encoded, "encoded bytes must not be null");
if (!payloadType.equals(byte[].class)) {
throw new MessageSerializationException(
"RAW_BYTES_TARGET_REQUIRED", "raw bytes codec decodes only to byte[]");
}
if (encoded.length > maxBytes) {
throw new MessageTooLargeException(
"RAW_BYTES_TOO_LARGE", "encoded payload exceeds " + maxBytes + " bytes");
}
return payloadType.cast(encoded.clone());
}
}
@@ -0,0 +1,32 @@
package dev.caskeleton.messaging.schema;
/**
* The compatibility mode a message type's schema evolution must satisfy.
*
* <p>Transitive modes check every historical version, not just the immediate predecessor. That
* matters for integration events, where a consumer may be several releases behind and a chain of
* individually-compatible changes can still be collectively breaking.
*/
public enum SchemaCompatibility {
/** A new schema can read data written by the previous schema. */
BACKWARD,
/** A new schema can read data written by every previous schema. */
BACKWARD_TRANSITIVE,
/** The previous schema can read data written by the new schema. */
FORWARD,
/** Every previous schema can read data written by the new schema. */
FORWARD_TRANSITIVE,
/** Both directions hold against the previous schema. */
FULL,
/** Both directions hold against every previous schema. */
FULL_TRANSITIVE,
/** No compatibility is enforced; permitted only for M2 raw bytes. */
NONE_EXPERIMENTAL
}
@@ -0,0 +1,113 @@
package dev.caskeleton.messaging.schema;
import dev.caskeleton.messaging.api.SchemaVersion;
import dev.caskeleton.messaging.api.error.MessageSchemaIncompatibleException;
import java.util.List;
import java.util.Objects;
/**
* The format-independent half of schema evolution: which versions have to be compared, and whether
* a mode is even allowed on a production destination.
*
* <p>Split from the per-format gates on purpose. Whether v3 must be checked against v1 as well as
* v2 is a property of the compatibility mode, not of Avro or Protobuf, and duplicating that
* reasoning in each codec is how the two formats drift apart.
*
* <p>{@link SchemaCompatibility#NONE_EXPERIMENTAL} is refused for production destinations. A mode
* that checks nothing is useful while a message type is being designed and actively dangerous once
* a retained log exists, because the log outlives every consumer that could still read it.
*/
public final class SchemaCompatibilityValidator {
private final SchemaRegistry registry;
/**
* Creates a validator over a registry.
*
* @param registry the schema source
*/
public SchemaCompatibilityValidator(SchemaRegistry registry) {
this.registry = Objects.requireNonNull(registry, "registry must not be null");
}
/**
* Returns the versions a candidate must be checked against, newest first.
*
* <p>Transitive modes return the whole history; pairwise modes return only the immediate
* predecessor; {@link SchemaCompatibility#NONE_EXPERIMENTAL} returns nothing.
*
* @param subject the registry subject
* @return the versions to compare against
*/
public List<SchemaVersion> versionsToCheck(String subject) {
Objects.requireNonNull(subject, "subject must not be null");
SchemaCompatibility mode = registry.compatibilityOf(subject);
if (mode == SchemaCompatibility.NONE_EXPERIMENTAL) {
return List.of();
}
List<SchemaVersion> history = registry.history(subject).reversed();
if (history.isEmpty()) {
return List.of();
}
return isTransitive(mode) ? history : List.of(history.get(0));
}
/**
* Refuses a compatibility mode that must not reach a production destination.
*
* @param subject the registry subject
* @param destination the logical destination name, used in the diagnostic
* @throws MessageSchemaIncompatibleException when the subject is unchecked
*/
public void requireProductionMode(String subject, String destination) {
Objects.requireNonNull(subject, "subject must not be null");
Objects.requireNonNull(destination, "destination must not be null");
if (registry.compatibilityOf(subject) == SchemaCompatibility.NONE_EXPERIMENTAL) {
throw new MessageSchemaIncompatibleException(
"UNCHECKED_SCHEMA_ON_PRODUCTION_DESTINATION",
"subject %s is NONE_EXPERIMENTAL and cannot back the production destination %s"
.formatted(subject, destination));
}
}
/**
* Reports whether readers must be able to read data written by older writers.
*
* @param mode the compatibility mode
* @return true when the backward direction is enforced
*/
public static boolean checksBackward(SchemaCompatibility mode) {
Objects.requireNonNull(mode, "mode must not be null");
return mode == SchemaCompatibility.BACKWARD
|| mode == SchemaCompatibility.BACKWARD_TRANSITIVE
|| mode == SchemaCompatibility.FULL
|| mode == SchemaCompatibility.FULL_TRANSITIVE;
}
/**
* Reports whether older readers must be able to read data written by the candidate.
*
* @param mode the compatibility mode
* @return true when the forward direction is enforced
*/
public static boolean checksForward(SchemaCompatibility mode) {
Objects.requireNonNull(mode, "mode must not be null");
return mode == SchemaCompatibility.FORWARD
|| mode == SchemaCompatibility.FORWARD_TRANSITIVE
|| mode == SchemaCompatibility.FULL
|| mode == SchemaCompatibility.FULL_TRANSITIVE;
}
/**
* Reports whether a mode compares against the whole history.
*
* @param mode the compatibility mode
* @return true for the transitive modes
*/
public static boolean isTransitive(SchemaCompatibility mode) {
Objects.requireNonNull(mode, "mode must not be null");
return mode == SchemaCompatibility.BACKWARD_TRANSITIVE
|| mode == SchemaCompatibility.FORWARD_TRANSITIVE
|| mode == SchemaCompatibility.FULL_TRANSITIVE;
}
}
@@ -0,0 +1,39 @@
package dev.caskeleton.messaging.schema;
import dev.caskeleton.messaging.api.SchemaVersion;
import java.net.URI;
import java.util.Objects;
import java.util.Optional;
/**
* Points at the schema an encoded payload was written against.
*
* <p>Carried alongside the bytes rather than inferred from the message type, because a consumer
* that guesses the schema from the type is exactly the consumer that breaks when a producer rolls
* forward.
*
* @param subject the registry subject or schema name
* @param version the schema revision
* @param schemaUri the resolvable schema location, when one exists
*/
public record SchemaReference(String subject, SchemaVersion version, Optional<URI> schemaUri) {
public SchemaReference {
Objects.requireNonNull(version, "schema version must not be null");
Objects.requireNonNull(schemaUri, "schemaUri must not be null");
if (subject == null || subject.isBlank()) {
throw new IllegalArgumentException("schema subject must not be blank");
}
}
/**
* Builds a reference with no resolvable location.
*
* @param subject the registry subject
* @param version the schema revision
* @return a schema reference
*/
public static SchemaReference of(String subject, SchemaVersion version) {
return new SchemaReference(subject, version, Optional.empty());
}
}
@@ -0,0 +1,56 @@
package dev.caskeleton.messaging.schema;
import dev.caskeleton.messaging.api.SchemaVersion;
import java.util.List;
import java.util.Optional;
/**
* Resolves schemas by subject and version, and records the compatibility mode each subject is held
* to.
*
* <p>Deliberately a port. A hosted registry, a classpath directory of schema files, and a static
* in-process map are all legitimate sources depending on the deployment, and the platform's
* compatibility rules must hold identically across all three. Binding to a vendor client here would
* make the rules untestable without that vendor running.
*
* <p>{@link #history} returns oldest first. Transitive compatibility checks read the whole list, so
* an ordering mistake here silently converts a transitive check into a pairwise one.
*/
public interface SchemaRegistry {
/**
* Resolves one schema definition.
*
* @param subject the registry subject
* @param version the schema revision
* @return the schema text, or empty when the subject or version is unknown
*/
Optional<String> lookup(String subject, SchemaVersion version);
/**
* Returns every registered version of a subject, oldest first.
*
* @param subject the registry subject
* @return the version history, empty when the subject is unknown
*/
List<SchemaVersion> history(String subject);
/**
* Returns the compatibility mode enforced for a subject.
*
* @param subject the registry subject
* @return the subject's compatibility mode
*/
SchemaCompatibility compatibilityOf(String subject);
/**
* Returns the newest registered version of a subject.
*
* @param subject the registry subject
* @return the latest version, or empty when the subject is unknown
*/
default Optional<SchemaVersion> latest(String subject) {
List<SchemaVersion> versions = history(subject);
return versions.isEmpty() ? Optional.empty() : Optional.of(versions.get(versions.size() - 1));
}
}
@@ -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();
}
}
@@ -0,0 +1,87 @@
package dev.caskeleton.messaging.schema;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatCode;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.messaging.api.error.MessageTooLargeException;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
/**
* The boundary the codecs delegate to.
*
* <p>Each codec used to serialize into an unbounded buffer and compare the finished length to the
* limit. That check reports an oversized payload; it does not prevent one. The difference only
* shows up for a payload whose serialized form is orders of magnitude larger than the bound, which
* is precisely the case that matters — the consumer is out of heap before the comparison runs.
*/
class BoundedByteSinkTest {
private static final int MAX = 64;
@Test
@DisplayName("one byte under, exactly at, and one byte over the limit")
void theLimitIsInclusiveAndTheNextByteIsRefused() {
assertThatCode(() -> fill(MAX - 1)).doesNotThrowAnyException();
assertThatCode(() -> fill(MAX)).doesNotThrowAnyException();
assertThatThrownBy(() -> fill(MAX + 1))
.isInstanceOf(MessageTooLargeException.class)
.hasMessageContaining("refused at byte 65");
}
@Test
@DisplayName("a much larger stream stops at the limit rather than after allocation")
void aMuchLargerStreamStopsAtTheLimit() {
BoundedByteSink sink = BoundedByteSink.of(MAX, "PAYLOAD_TOO_LARGE");
assertThatThrownBy(
() -> {
// Ten mebibytes offered one kibibyte at a time. A buffer-then-check codec would have
// held all of it; this refuses the chunk that crosses the bound.
for (int chunk = 0; chunk < 10_240; chunk++) {
sink.write(new byte[1_024], 0, 1_024);
}
})
.isInstanceOf(MessageTooLargeException.class);
assertThat(sink.written())
.as("nothing beyond the bound was ever admitted")
.isLessThanOrEqualTo(MAX);
assertThat(sink.toByteArray()).isEmpty();
}
@Test
@DisplayName("a pre-flight size check does not consume the budget")
void aPreFlightCheckDoesNotConsumeTheBudget() {
BoundedByteSink sink = BoundedByteSink.of(MAX, "PAYLOAD_TOO_LARGE");
sink.requireFits(MAX);
assertThat(sink.written()).isZero();
assertThatCode(() -> sink.write(new byte[MAX], 0, MAX)).doesNotThrowAnyException();
}
@Test
@DisplayName("a pre-flight check refuses a size that cannot fit")
void aPreFlightCheckRefusesASizeThatCannotFit() {
BoundedByteSink sink = BoundedByteSink.of(MAX, "AVRO_PAYLOAD_TOO_LARGE");
assertThatThrownBy(() -> sink.requireFits(MAX + 1))
.isInstanceOf(MessageTooLargeException.class)
.asInstanceOf(
org.assertj.core.api.InstanceOfAssertFactories.type(MessageTooLargeException.class))
.extracting(failure -> failure.failure().code())
.as("the sink reports the codec's own code, not a generic one")
.isEqualTo("AVRO_PAYLOAD_TOO_LARGE");
}
private static byte[] fill(int size) {
BoundedByteSink sink = BoundedByteSink.of(MAX, "PAYLOAD_TOO_LARGE");
for (int index = 0; index < size; index++) {
sink.write('a');
}
return sink.toByteArray();
}
}
@@ -0,0 +1,67 @@
package dev.caskeleton.messaging.schema;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.messaging.api.ContentType;
import dev.caskeleton.messaging.api.MessageType;
import dev.caskeleton.messaging.api.SchemaVersion;
import dev.caskeleton.messaging.api.error.MessageSerializationException;
import dev.caskeleton.messaging.api.error.MessageTooLargeException;
import java.util.Optional;
import org.junit.jupiter.api.Test;
class RawBytesMessageCodecTest {
private static final MessageType OPAQUE = new MessageType("opaque.blob");
private static final SchemaVersion V1 = new SchemaVersion(1);
private final RawBytesMessageCodec codec = new RawBytesMessageCodec();
@Test
void roundTripsOpaqueBytes() {
byte[] payload = {1, 2, 3, 4};
EncodedMessage encoded = codec.encode(OPAQUE, V1, payload);
assertThat(codec.decode(OPAQUE, V1, encoded.bytes(), byte[].class)).containsExactly(1, 2, 3, 4);
}
@Test
void advertisesOpaqueContentTypeAndNoSchemaReference() {
EncodedMessage encoded = codec.encode(OPAQUE, V1, new byte[] {9});
assertThat(codec.contentType()).isEqualTo(ContentType.OCTET_STREAM);
assertThat(encoded.schemaReference()).isEmpty();
}
@Test
void refusesNonByteArrayPayloads() {
assertThatThrownBy(() -> codec.encode(OPAQUE, V1, "text"))
.isInstanceOf(MessageSerializationException.class);
}
@Test
void refusesDecodingToAnythingButByteArray() {
assertThatThrownBy(() -> codec.decode(OPAQUE, V1, new byte[] {1}, String.class))
.isInstanceOf(MessageSerializationException.class);
}
@Test
void enforcesTheByteLimit() {
RawBytesMessageCodec small = new RawBytesMessageCodec(4);
assertThatThrownBy(() -> small.encode(OPAQUE, V1, new byte[5]))
.isInstanceOf(MessageTooLargeException.class);
}
@Test
void encodedMessageDefensivelyCopiesItsBytes() {
byte[] source = {1, 2, 3};
EncodedMessage encoded = new EncodedMessage(source, ContentType.OCTET_STREAM, Optional.empty());
source[0] = 99;
assertThat(encoded.bytes()).containsExactly(1, 2, 3);
}
}
@@ -0,0 +1,109 @@
package dev.caskeleton.messaging.schema;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatCode;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.messaging.api.SchemaVersion;
import dev.caskeleton.messaging.api.error.MessageSchemaIncompatibleException;
import java.util.List;
import java.util.Optional;
import org.junit.jupiter.api.Test;
class SchemaCompatibilityValidatorTest {
private static final SchemaVersion V1 = new SchemaVersion(1);
private static final SchemaVersion V2 = new SchemaVersion(2);
private static final SchemaVersion V3 = new SchemaVersion(3);
/** A registry whose history is deliberately oldest-first, as the port documents. */
private record FixedRegistry(List<SchemaVersion> versions, SchemaCompatibility mode)
implements SchemaRegistry {
@Override
public Optional<String> lookup(String subject, SchemaVersion version) {
return versions.contains(version) ? Optional.of("{}") : Optional.empty();
}
@Override
public List<SchemaVersion> history(String subject) {
return versions;
}
@Override
public SchemaCompatibility compatibilityOf(String subject) {
return mode;
}
}
private static SchemaCompatibilityValidator validator(SchemaCompatibility mode) {
return new SchemaCompatibilityValidator(new FixedRegistry(List.of(V1, V2, V3), mode));
}
@Test
void aPairwiseModeChecksOnlyTheImmediatePredecessor() {
assertThat(validator(SchemaCompatibility.BACKWARD).versionsToCheck("order.created"))
.containsExactly(V3);
}
@Test
void aTransitiveModeChecksTheWholeHistoryNewestFirst() {
assertThat(validator(SchemaCompatibility.BACKWARD_TRANSITIVE).versionsToCheck("order.created"))
.as(
"a chain of individually compatible changes can still break a consumer several releases behind")
.containsExactly(V3, V2, V1);
}
@Test
void anUncheckedModeComparesAgainstNothing() {
assertThat(validator(SchemaCompatibility.NONE_EXPERIMENTAL).versionsToCheck("order.created"))
.isEmpty();
}
@Test
void anEmptyHistoryHasNothingToCompareAgainst() {
SchemaCompatibilityValidator validator =
new SchemaCompatibilityValidator(
new FixedRegistry(List.of(), SchemaCompatibility.FULL_TRANSITIVE));
assertThat(validator.versionsToCheck("order.created")).isEmpty();
}
@Test
void anUncheckedSubjectCannotBackAProductionDestination() {
assertThatThrownBy(
() ->
validator(SchemaCompatibility.NONE_EXPERIMENTAL)
.requireProductionMode("order.created", "orders.v1"))
.isInstanceOf(MessageSchemaIncompatibleException.class)
.hasMessageContaining("orders.v1");
}
@Test
void aCheckedSubjectMayBackAProductionDestination() {
assertThatCode(
() ->
validator(SchemaCompatibility.FULL)
.requireProductionMode("order.created", "orders.v1"))
.doesNotThrowAnyException();
}
@Test
void fullModeEnforcesBothDirections() {
assertThat(SchemaCompatibilityValidator.checksBackward(SchemaCompatibility.FULL)).isTrue();
assertThat(SchemaCompatibilityValidator.checksForward(SchemaCompatibility.FULL)).isTrue();
}
@Test
void eachOneDirectionalModeEnforcesOnlyItsOwnDirection() {
assertThat(SchemaCompatibilityValidator.checksForward(SchemaCompatibility.BACKWARD)).isFalse();
assertThat(SchemaCompatibilityValidator.checksBackward(SchemaCompatibility.FORWARD)).isFalse();
}
@Test
void theLatestVersionIsTheNewestNotTheFirstListed() {
SchemaRegistry registry = new FixedRegistry(List.of(V1, V2, V3), SchemaCompatibility.FULL);
assertThat(registry.latest("order.created")).hasValue(V3);
}
}