review-followup Wave 3 라운드 3(P21): messaging 플랫폼 — Kafka 소비(MessageHandler 하나), API 정리
- 결정 10: consume 계약을 `MessageHandler<T>` 하나로, starter-kafka가 consumer 조립(handler bean이 있으면 켜짐, `app.messaging.enabled=false`로 끔). 오프셋은 handler Success(inbox면 트랜잭션 커밋) 뒤 또는 DLQ 쓰기 확인 뒤에만 커밋, auto-commit 금지, `read_committed`, 재시도 소진 → DLQ(없으면 멈춤) — Kafka+PG로 왕복·중복 제거·DLQ 검증 - 미사용 API 타입·Blocking/Reactive/Batch facade·reactor api 노출 삭제, `PublishResult` 정적 factory, `MessagingCapabilities` → EnumSet, API leaf 병합(core-api+schema-api, admin-api+admin-runtime), starter god config 분해, Kafka broker 설정은 starter-kafka로, 등급 용어 정리 - 결함 수정: Retry 응답이 시도 횟수를 세지 않아 partition 정지(P21-new-1), deliveryAttempt 항상 1(P21-new-2) - 통합: app-bootstrap `MessagingPublicSurfaceContractTest` 기대값을 P21 변경에 맞춤, starter-kafka에 `api kafka-clients` 검증: ./gradlew check architectureCheck verifyDependencyLocks :app-bootstrap:verifyEnvKeys :app-bootstrap:integrationTest :sample-portfolio:integrationTest :messaging:messaging-spring-boot-starter:integrationTest :messaging:messaging-reliability-jdbc-postgresql:integrationTest mainCheck --continue 통과(812 task) Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 5.5
parent
6397f52dc8
commit
763392c8b2
-46
@@ -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();
|
||||
}
|
||||
}
|
||||
-29
@@ -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()));
|
||||
}
|
||||
}
|
||||
}
|
||||
-24
@@ -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);
|
||||
}
|
||||
+18
-3
@@ -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.
|
||||
*
|
||||
|
||||
-33
@@ -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);
|
||||
}
|
||||
-11
@@ -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
|
||||
}
|
||||
-15
@@ -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);
|
||||
}
|
||||
+55
-27
@@ -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"));
|
||||
}
|
||||
}
|
||||
|
||||
-49
@@ -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);
|
||||
}
|
||||
}
|
||||
-49
@@ -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);
|
||||
}
|
||||
}
|
||||
-49
@@ -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);
|
||||
}
|
||||
}
|
||||
-54
@@ -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);
|
||||
}
|
||||
}
|
||||
-54
@@ -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);
|
||||
}
|
||||
}
|
||||
-49
@@ -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);
|
||||
}
|
||||
}
|
||||
-54
@@ -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);
|
||||
}
|
||||
}
|
||||
-53
@@ -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);
|
||||
}
|
||||
}
|
||||
-49
@@ -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);
|
||||
}
|
||||
}
|
||||
-49
@@ -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);
|
||||
}
|
||||
}
|
||||
-49
@@ -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);
|
||||
}
|
||||
}
|
||||
-49
@@ -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);
|
||||
}
|
||||
}
|
||||
-53
@@ -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);
|
||||
}
|
||||
}
|
||||
-25
@@ -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);
|
||||
}
|
||||
-27
@@ -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");
|
||||
}
|
||||
}
|
||||
}
|
||||
-42
@@ -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);
|
||||
}
|
||||
}
|
||||
-44
@@ -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);
|
||||
}
|
||||
}
|
||||
-30
@@ -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);
|
||||
}
|
||||
-28
@@ -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);
|
||||
}
|
||||
+64
@@ -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.
|
||||
*
|
||||
|
||||
-25
@@ -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);
|
||||
}
|
||||
-50
@@ -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);
|
||||
}
|
||||
+114
@@ -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;
|
||||
}
|
||||
}
|
||||
+66
@@ -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 + "]";
|
||||
}
|
||||
}
|
||||
+24
@@ -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);
|
||||
}
|
||||
+59
@@ -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);
|
||||
}
|
||||
}
|
||||
+26
@@ -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();
|
||||
}
|
||||
+49
@@ -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();
|
||||
}
|
||||
}
|
||||
+76
@@ -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());
|
||||
}
|
||||
}
|
||||
+32
@@ -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
|
||||
}
|
||||
+113
@@ -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;
|
||||
}
|
||||
}
|
||||
+39
@@ -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());
|
||||
}
|
||||
}
|
||||
+56
@@ -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));
|
||||
}
|
||||
}
|
||||
+18
-3
@@ -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
|
||||
|
||||
+44
@@ -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();
|
||||
}
|
||||
}
|
||||
|
||||
+87
@@ -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();
|
||||
}
|
||||
}
|
||||
+67
@@ -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);
|
||||
}
|
||||
}
|
||||
+109
@@ -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);
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user