feat(messaging): 브로커 중립 메시징 플랫폼 24개 leaf 추가
messaging-superpowers-package 설계서/계획서 기반 구현. registry를 19 → 43 leaf로 확장하고 src/messaging 아래 24개 leaf를 등록. - core-api: M1 publish/consume + M2 batch·delayed·pause-resume - policy/transport-spi: 재시도 결정, DLQ orchestration, admission control, lifecycle - kafka·rabbit(Stable): contiguous commit, confirm/return 상관, 배치, 보안 설정 - pulsar·nats(Experimental): 기본 비활성, live 인증 없음을 코드로 기록 - outbox/inbox/claim-check: 트랜잭션 결합, lease, 무결성 검증 - admin: plan → approve → execute를 타입으로 강제 - 문서 9종, infra compose 7종, JMH 벤치마크 3종 검증: 아키텍처 게이트 3종 통과, 24개 leaf 전부 check 통과, messaging 테스트 604개 통과/0 실패. 미완: 계획서가 요구한 실 브로커 IT 40개 중 7개만 작성. Rabbit 13 / Outbox 6 / Inbox 4 / NATS·Pulsar·Share 5 / testkit 2 / starter·admin 3, 그리고 TLS·ACL 2개가 남음.
This commit is contained in:
@@ -0,0 +1,5 @@
|
||||
apply plugin: 'java-library'
|
||||
|
||||
dependencies {
|
||||
api project(':messaging:messaging-core-api')
|
||||
}
|
||||
@@ -0,0 +1,83 @@
|
||||
# This is a Gradle generated file for dependency locking.
|
||||
# Manual edits can break the build and are not advised.
|
||||
# This file is expected to be part of source control.
|
||||
com.github.ben-manes.caffeine:caffeine:3.2.3=annotationProcessor,testAnnotationProcessor
|
||||
com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,testAnnotationProcessor
|
||||
com.github.spotbugs:spotbugs-annotations:4.10.2=spotbugs
|
||||
com.github.spotbugs:spotbugs:4.10.2=spotbugs
|
||||
com.github.stephenc.jcip:jcip-annotations:1.0-1=spotbugs
|
||||
com.google.auto.service:auto-service-annotations:1.0.1=annotationProcessor,testAnnotationProcessor
|
||||
com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,testAnnotationProcessor
|
||||
com.google.auto:auto-common:1.2.2=annotationProcessor,testAnnotationProcessor
|
||||
com.google.code.findbugs:jsr305:3.0.2=checkstyle,spotbugs
|
||||
com.google.code.gson:gson:2.13.2=spotbugs
|
||||
com.google.errorprone:error_prone_annotation:2.49.0=annotationProcessor,testAnnotationProcessor
|
||||
com.google.errorprone:error_prone_annotations:2.41.0=spotbugs
|
||||
com.google.errorprone:error_prone_annotations:2.47.0=checkstyle
|
||||
com.google.errorprone:error_prone_annotations:2.49.0=annotationProcessor,testAnnotationProcessor
|
||||
com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,testAnnotationProcessor
|
||||
com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,testAnnotationProcessor
|
||||
com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,testAnnotationProcessor
|
||||
com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,testAnnotationProcessor
|
||||
com.google.guava:guava:33.5.0-jre=annotationProcessor,testAnnotationProcessor
|
||||
com.google.guava:guava:33.6.0-jre=checkstyle
|
||||
com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,testAnnotationProcessor
|
||||
com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,testAnnotationProcessor
|
||||
com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,testAnnotationProcessor
|
||||
com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0=spotbugsPlugins
|
||||
com.puppycrawl.tools:checkstyle:13.5.0=checkstyle
|
||||
commons-beanutils:commons-beanutils:1.11.0=checkstyle
|
||||
commons-collections:commons-collections:3.2.2=checkstyle
|
||||
commons-io:commons-io:2.21.0=spotbugs
|
||||
info.picocli:picocli:4.7.7=checkstyle
|
||||
io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,testAnnotationProcessor
|
||||
io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,testAnnotationProcessor
|
||||
javax.inject:javax.inject:1=annotationProcessor,testAnnotationProcessor
|
||||
jaxen:jaxen:2.0.0=spotbugs
|
||||
net.bytebuddy:byte-buddy:1.17.8=testCompileClasspath,testRuntimeClasspath
|
||||
net.sf.saxon:Saxon-HE:12.9=checkstyle,spotbugs
|
||||
org.antlr:antlr4-runtime:4.13.2=checkstyle
|
||||
org.apache.bcel:bcel:6.12.0=spotbugs
|
||||
org.apache.commons:commons-lang3:3.20.0=checkstyle,spotbugs
|
||||
org.apache.commons:commons-text:1.15.0=spotbugs
|
||||
org.apache.commons:commons-text:1.3=checkstyle
|
||||
org.apache.httpcomponents:httpclient:4.5.13=checkstyle
|
||||
org.apache.httpcomponents:httpcore:4.4.16=checkstyle
|
||||
org.apache.logging.log4j:log4j-api:2.25.2=spotbugs
|
||||
org.apache.logging.log4j:log4j-core:2.25.2=spotbugs
|
||||
org.apache.maven.doxia:doxia-core:1.12.0=checkstyle
|
||||
org.apache.maven.doxia:doxia-logging-api:1.12.0=checkstyle
|
||||
org.apache.maven.doxia:doxia-module-xdoc:1.12.0=checkstyle
|
||||
org.apache.maven.doxia:doxia-sink-api:1.12.0=checkstyle
|
||||
org.apache.xbean:xbean-reflect:3.7=checkstyle
|
||||
org.apiguardian:apiguardian-api:1.1.2=testCompileClasspath
|
||||
org.assertj:assertj-core:3.27.6=testCompileClasspath,testRuntimeClasspath
|
||||
org.codehaus.plexus:plexus-classworlds:2.6.0=checkstyle
|
||||
org.codehaus.plexus:plexus-component-annotations:2.1.0=checkstyle
|
||||
org.codehaus.plexus:plexus-container-default:2.1.0=checkstyle
|
||||
org.codehaus.plexus:plexus-utils:3.3.0=checkstyle
|
||||
org.dom4j:dom4j:2.2.0=spotbugs
|
||||
org.javassist:javassist:3.28.0-GA=checkstyle
|
||||
org.jspecify:jspecify:1.0.0=annotationProcessor,checkstyle,testAnnotationProcessor,testCompileClasspath
|
||||
org.junit.jupiter:junit-jupiter-api:6.0.1=testCompileClasspath,testRuntimeClasspath
|
||||
org.junit.jupiter:junit-jupiter-engine:6.0.1=testRuntimeClasspath
|
||||
org.junit.jupiter:junit-jupiter-params:6.0.1=testCompileClasspath,testRuntimeClasspath
|
||||
org.junit.jupiter:junit-jupiter:6.0.1=testCompileClasspath,testRuntimeClasspath
|
||||
org.junit.platform:junit-platform-commons:6.0.1=testCompileClasspath,testRuntimeClasspath
|
||||
org.junit.platform:junit-platform-engine:6.0.1=testRuntimeClasspath
|
||||
org.junit.platform:junit-platform-launcher:6.0.1=testRuntimeClasspath
|
||||
org.junit:junit-bom:6.0.1=testCompileClasspath,testRuntimeClasspath
|
||||
org.junit:junit-bom:6.1.0=spotbugs
|
||||
org.mockito:mockito-core:5.20.0=mockitoAgent
|
||||
org.opentest4j:opentest4j:1.3.0=testCompileClasspath,testRuntimeClasspath
|
||||
org.ow2.asm:asm-analysis:9.10.1=spotbugs
|
||||
org.ow2.asm:asm-commons:9.10.1=spotbugs
|
||||
org.ow2.asm:asm-tree:9.10.1=spotbugs
|
||||
org.ow2.asm:asm-util:9.10.1=spotbugs
|
||||
org.ow2.asm:asm:9.10.1=spotbugs
|
||||
org.pcollections:pcollections:4.0.1=annotationProcessor,testAnnotationProcessor
|
||||
org.reflections:reflections:0.10.2=checkstyle
|
||||
org.slf4j:slf4j-api:2.0.17=spotbugs,spotbugsSlf4j
|
||||
org.slf4j:slf4j-simple:2.0.17=checkstyle,spotbugsSlf4j
|
||||
org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs
|
||||
empty=compileClasspath,runtimeClasspath
|
||||
+50
@@ -0,0 +1,50 @@
|
||||
package dev.caskeleton.messaging.reliability;
|
||||
|
||||
import java.time.Instant;
|
||||
import java.util.Objects;
|
||||
import java.util.regex.Pattern;
|
||||
|
||||
/**
|
||||
* Points at a payload stored outside the broker.
|
||||
*
|
||||
* <p>The digest is part of the reference, not an optional extra. A claim check splits a message
|
||||
* into two systems with independent retention and replication, so a consumer that fetches the
|
||||
* payload has to be able to prove it got the bytes the producer stored — otherwise a truncated or
|
||||
* replaced object is indistinguishable from a valid one.
|
||||
*
|
||||
* <p>The expiry is carried for the same reason: a claim check whose payload has been reaped is a
|
||||
* dead message, and detecting that at fetch time is better than a mysterious not-found.
|
||||
*
|
||||
* @param storageKey the object key in the payload store
|
||||
* @param sizeBytes the stored payload size
|
||||
* @param sha256 the lowercase hex digest of the stored payload
|
||||
* @param expiresAt when the payload store may reap the object
|
||||
*/
|
||||
public record ClaimCheckReference(
|
||||
String storageKey, long sizeBytes, String sha256, Instant expiresAt) {
|
||||
|
||||
private static final Pattern SHA256 = Pattern.compile("[a-f0-9]{64}");
|
||||
|
||||
public ClaimCheckReference {
|
||||
Objects.requireNonNull(expiresAt, "expiresAt must not be null");
|
||||
if (storageKey == null || storageKey.isBlank()) {
|
||||
throw new IllegalArgumentException("storageKey must not be blank");
|
||||
}
|
||||
if (sizeBytes < 0) {
|
||||
throw new IllegalArgumentException("sizeBytes must not be negative");
|
||||
}
|
||||
if (sha256 == null || !SHA256.matcher(sha256).matches()) {
|
||||
throw new IllegalArgumentException("sha256 must be 64 lowercase hex characters");
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Reports whether the payload store may already have reaped this object.
|
||||
*
|
||||
* @param now the current instant
|
||||
* @return true once the retention window has passed
|
||||
*/
|
||||
public boolean isExpired(Instant now) {
|
||||
return !now.isBefore(expiresAt);
|
||||
}
|
||||
}
|
||||
+33
@@ -0,0 +1,33 @@
|
||||
package dev.caskeleton.messaging.reliability;
|
||||
|
||||
import dev.caskeleton.messaging.api.delivery.HandleResult;
|
||||
import dev.caskeleton.messaging.api.delivery.MessageDelivery;
|
||||
import java.util.concurrent.CompletionStage;
|
||||
|
||||
/**
|
||||
* Runs a side effect at most once per consumer, whatever the broker redelivers.
|
||||
*
|
||||
* <p>{@code consumerName} is a parameter rather than a property of the message because the same
|
||||
* message legitimately reaches several independent consumers, and each of them is entitled to apply
|
||||
* its own effect once. Keying the inbox on the message id alone would let whichever consumer ran
|
||||
* first suppress all the others.
|
||||
*
|
||||
* <p>A duplicate is not a failure. The handler returns success for a message it has already
|
||||
* applied, so the broker settles it and stops redelivering; treating it as an error would park a
|
||||
* message whose work is already done.
|
||||
*
|
||||
* @param <T> the payload type
|
||||
*/
|
||||
public interface IdempotentMessageHandler<T> {
|
||||
|
||||
/**
|
||||
* Applies an action once for a given consumer.
|
||||
*
|
||||
* @param consumerName the consumer identity the reservation is keyed on
|
||||
* @param delivery the message being handled
|
||||
* @param action the effect to apply inside the reservation's transaction
|
||||
* @return a stage completing with the handler outcome
|
||||
*/
|
||||
CompletionStage<HandleResult> handleOnce(
|
||||
String consumerName, MessageDelivery<T> delivery, TransactionalMessageAction<T> action);
|
||||
}
|
||||
+27
@@ -0,0 +1,27 @@
|
||||
package dev.caskeleton.messaging.reliability;
|
||||
|
||||
import dev.caskeleton.messaging.api.MessageId;
|
||||
import java.time.Instant;
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* One row of the consumer inbox.
|
||||
*
|
||||
* <p>Keyed by message id <em>and</em> consumer id, because two independent consumers of the same
|
||||
* event must each process it once — deduplicating on the message alone would let the first consumer
|
||||
* suppress the second.
|
||||
*
|
||||
* @param messageId the logical message identity
|
||||
* @param consumerId the consumer's stable identity
|
||||
* @param processedAt when the side effect committed
|
||||
*/
|
||||
public record InboxRecord(MessageId messageId, String consumerId, Instant processedAt) {
|
||||
|
||||
public InboxRecord {
|
||||
Objects.requireNonNull(messageId, "messageId must not be null");
|
||||
Objects.requireNonNull(processedAt, "processedAt must not be null");
|
||||
if (consumerId == null || consumerId.isBlank()) {
|
||||
throw new IllegalArgumentException("consumerId must not be blank");
|
||||
}
|
||||
}
|
||||
}
|
||||
+46
@@ -0,0 +1,46 @@
|
||||
package dev.caskeleton.messaging.reliability;
|
||||
|
||||
import dev.caskeleton.messaging.api.MessageId;
|
||||
import java.time.Instant;
|
||||
|
||||
/**
|
||||
* Storage for consumer-side deduplication.
|
||||
*
|
||||
* <p>{@link #reserve} must run inside the same database transaction as the handler's side effect.
|
||||
* That is the entire mechanism: the uniqueness constraint on the inbox row and the business write
|
||||
* commit together, so a redelivered message either finds the row already present and skips, or
|
||||
* writes both. Reserving in a separate transaction reintroduces exactly the gap the Inbox exists to
|
||||
* close.
|
||||
*/
|
||||
public interface InboxRepository {
|
||||
|
||||
/**
|
||||
* Reserves a message for processing inside the caller's transaction.
|
||||
*
|
||||
* @param messageId the logical message identity
|
||||
* @param consumerId the consumer's stable identity
|
||||
* @param now the current instant
|
||||
* @return true when this is the first time; false when it was already processed
|
||||
*/
|
||||
boolean reserve(MessageId messageId, String consumerId, Instant now);
|
||||
|
||||
/**
|
||||
* Reports whether a message has already been processed by a consumer.
|
||||
*
|
||||
* @param messageId the logical message identity
|
||||
* @param consumerId the consumer's stable identity
|
||||
* @return true when already recorded
|
||||
*/
|
||||
boolean isProcessed(MessageId messageId, String consumerId);
|
||||
|
||||
/**
|
||||
* Deletes records older than a cutoff.
|
||||
*
|
||||
* <p>Retention must outlive the broker's maximum redelivery window, otherwise a late redelivery
|
||||
* arrives after its inbox row was pruned and is processed a second time.
|
||||
*
|
||||
* @param processedBefore the retention cutoff
|
||||
* @return how many rows were removed
|
||||
*/
|
||||
int purgeProcessedBefore(Instant processedBefore);
|
||||
}
|
||||
+45
@@ -0,0 +1,45 @@
|
||||
package dev.caskeleton.messaging.reliability;
|
||||
|
||||
/**
|
||||
* What the inbox decided about one delivery.
|
||||
*
|
||||
* <p>Three outcomes, not two. Collapsing {@link #ALREADY_APPLIED} and {@link #CLAIMED_ELSEWHERE}
|
||||
* into a single "duplicate" would settle a message whose effect is still only half-written by
|
||||
* another instance: if that instance then rolls back, the effect is lost and the broker will never
|
||||
* redeliver, because this instance already acknowledged it.
|
||||
*/
|
||||
public enum InboxResult {
|
||||
|
||||
/** No reservation existed; the effect ran inside this transaction. */
|
||||
APPLIED(true),
|
||||
|
||||
/**
|
||||
* A committed reservation already exists, so the effect ran before.
|
||||
*
|
||||
* <p>Settle the message: the work is done and redelivering it achieves nothing.
|
||||
*/
|
||||
ALREADY_APPLIED(true),
|
||||
|
||||
/**
|
||||
* Another instance holds an uncommitted reservation for this message.
|
||||
*
|
||||
* <p>Do <em>not</em> settle. The other transaction may still roll back, and this delivery is the
|
||||
* only remaining copy that could re-apply the effect.
|
||||
*/
|
||||
CLAIMED_ELSEWHERE(false);
|
||||
|
||||
private final boolean safeToSettle;
|
||||
|
||||
InboxResult(boolean safeToSettle) {
|
||||
this.safeToSettle = safeToSettle;
|
||||
}
|
||||
|
||||
/**
|
||||
* Reports whether the source message may be settled on this outcome.
|
||||
*
|
||||
* @return true when settling cannot lose the effect
|
||||
*/
|
||||
public boolean isSafeToSettle() {
|
||||
return safeToSettle;
|
||||
}
|
||||
}
|
||||
+131
@@ -0,0 +1,131 @@
|
||||
package dev.caskeleton.messaging.reliability;
|
||||
|
||||
import dev.caskeleton.messaging.api.ContentType;
|
||||
import dev.caskeleton.messaging.api.MessageId;
|
||||
import dev.caskeleton.messaging.api.MessageType;
|
||||
import dev.caskeleton.messaging.api.SchemaVersion;
|
||||
import dev.caskeleton.messaging.api.destination.DestinationName;
|
||||
import java.time.Instant;
|
||||
import java.util.Arrays;
|
||||
import java.util.Map;
|
||||
import java.util.Objects;
|
||||
import java.util.Optional;
|
||||
|
||||
/**
|
||||
* One row of the transactional outbox.
|
||||
*
|
||||
* <p>The whole point of the pattern is that this row is written in the <em>same</em> database
|
||||
* transaction as the business change. Either both commit or neither does, which removes the window
|
||||
* where a service updates its state and then dies before publishing.
|
||||
*
|
||||
* <p>What the outbox does not do is remove duplicates. A relay that cannot confirm a publish will
|
||||
* retry it, and the same message may reach the broker twice. Effectively-once processing comes from
|
||||
* this row carrying a stable {@code messageId} and the consumer having an Inbox — not from the
|
||||
* outbox alone.
|
||||
*
|
||||
* @param messageId the stable logical identity, preserved across every retry
|
||||
* @param destination the logical destination
|
||||
* @param messageType the catalog message type
|
||||
* @param schemaVersion the payload schema revision
|
||||
* @param contentType the codec media type
|
||||
* @param payload the encoded payload
|
||||
* @param headers the reserved and application headers to publish
|
||||
* @param createdAt when the business transaction wrote this row
|
||||
* @param status the current lifecycle state
|
||||
* @param attempts how many publish attempts have been made
|
||||
* @param leaseExpiresAt when the current relay lease expires
|
||||
* @param lastFailureCode the last sanitized failure code
|
||||
*/
|
||||
@SuppressWarnings("ArrayRecordComponent")
|
||||
public record OutboxRecord(
|
||||
MessageId messageId,
|
||||
DestinationName destination,
|
||||
MessageType messageType,
|
||||
SchemaVersion schemaVersion,
|
||||
ContentType contentType,
|
||||
byte[] payload,
|
||||
Map<String, String> headers,
|
||||
Instant createdAt,
|
||||
OutboxStatus status,
|
||||
int attempts,
|
||||
Optional<Instant> leaseExpiresAt,
|
||||
Optional<String> lastFailureCode) {
|
||||
|
||||
public OutboxRecord {
|
||||
Objects.requireNonNull(messageId, "messageId must not be null");
|
||||
Objects.requireNonNull(destination, "destination must not be null");
|
||||
Objects.requireNonNull(messageType, "messageType must not be null");
|
||||
Objects.requireNonNull(schemaVersion, "schemaVersion must not be null");
|
||||
Objects.requireNonNull(contentType, "contentType must not be null");
|
||||
Objects.requireNonNull(payload, "payload must not be null");
|
||||
Objects.requireNonNull(headers, "headers must not be null");
|
||||
Objects.requireNonNull(createdAt, "createdAt must not be null");
|
||||
Objects.requireNonNull(status, "status must not be null");
|
||||
Objects.requireNonNull(leaseExpiresAt, "leaseExpiresAt must not be null");
|
||||
Objects.requireNonNull(lastFailureCode, "lastFailureCode must not be null");
|
||||
if (attempts < 0) {
|
||||
throw new IllegalArgumentException("attempts must not be negative");
|
||||
}
|
||||
payload = payload.clone();
|
||||
headers = Map.copyOf(headers);
|
||||
}
|
||||
|
||||
@Override
|
||||
public byte[] payload() {
|
||||
return payload.clone();
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns a copy in a new lifecycle state.
|
||||
*
|
||||
* <p>The message id is never a parameter, so no state transition can change it.
|
||||
*
|
||||
* @param newStatus the new status
|
||||
* @param newAttempts the updated attempt count
|
||||
* @param failureCode the last sanitized failure code
|
||||
* @return the updated record
|
||||
*/
|
||||
public OutboxRecord withStatus(
|
||||
OutboxStatus newStatus, int newAttempts, Optional<String> failureCode) {
|
||||
return new OutboxRecord(
|
||||
messageId,
|
||||
destination,
|
||||
messageType,
|
||||
schemaVersion,
|
||||
contentType,
|
||||
payload,
|
||||
headers,
|
||||
createdAt,
|
||||
newStatus,
|
||||
newAttempts,
|
||||
leaseExpiresAt,
|
||||
failureCode);
|
||||
}
|
||||
|
||||
@Override
|
||||
public boolean equals(Object other) {
|
||||
return other instanceof OutboxRecord record
|
||||
&& messageId.equals(record.messageId)
|
||||
&& status == record.status
|
||||
&& attempts == record.attempts
|
||||
&& Arrays.equals(payload, record.payload);
|
||||
}
|
||||
|
||||
@Override
|
||||
public int hashCode() {
|
||||
return Objects.hash(messageId, status, attempts, Arrays.hashCode(payload));
|
||||
}
|
||||
|
||||
@Override
|
||||
public String toString() {
|
||||
return "OutboxRecord[messageId="
|
||||
+ messageId.value()
|
||||
+ ", destination="
|
||||
+ destination.value()
|
||||
+ ", status="
|
||||
+ status
|
||||
+ ", attempts="
|
||||
+ attempts
|
||||
+ "]";
|
||||
}
|
||||
}
|
||||
+88
@@ -0,0 +1,88 @@
|
||||
package dev.caskeleton.messaging.reliability;
|
||||
|
||||
import dev.caskeleton.messaging.api.MessageId;
|
||||
import java.time.Duration;
|
||||
import java.time.Instant;
|
||||
import java.util.List;
|
||||
import java.util.Optional;
|
||||
|
||||
/**
|
||||
* Storage for the transactional outbox.
|
||||
*
|
||||
* <p>{@link #append} must be callable inside the caller's business transaction; every other method
|
||||
* runs in the relay's own transaction.
|
||||
*/
|
||||
public interface OutboxRepository {
|
||||
|
||||
/**
|
||||
* Appends a record inside the caller's transaction.
|
||||
*
|
||||
* @param record the record to write
|
||||
*/
|
||||
void append(OutboxRecord record);
|
||||
|
||||
/**
|
||||
* Leases a batch of publishable records.
|
||||
*
|
||||
* <p>Leasing rather than simply selecting is what makes multiple relay instances safe: a record
|
||||
* claimed by one relay is invisible to the others until its lease expires, so the same message is
|
||||
* not published concurrently by two processes.
|
||||
*
|
||||
* @param batchSize how many records to claim
|
||||
* @param leaseDuration how long the claim holds
|
||||
* @param now the current instant
|
||||
* @return the leased records, oldest first
|
||||
*/
|
||||
List<OutboxRecord> leaseBatch(int batchSize, Duration leaseDuration, Instant now);
|
||||
|
||||
/**
|
||||
* Marks a record as confirmed by the broker.
|
||||
*
|
||||
* @param messageId the record identity
|
||||
* @param now the current instant
|
||||
*/
|
||||
void markPublished(MessageId messageId, Instant now);
|
||||
|
||||
/**
|
||||
* Marks a record whose publish outcome is unknown.
|
||||
*
|
||||
* <p>The record stays eligible for retry under the same identity.
|
||||
*
|
||||
* @param messageId the record identity
|
||||
* @param failureCode the sanitized failure code
|
||||
* @param now the current instant
|
||||
*/
|
||||
void markAmbiguous(MessageId messageId, String failureCode, Instant now);
|
||||
|
||||
/**
|
||||
* Marks a record the broker definitively rejected.
|
||||
*
|
||||
* @param messageId the record identity
|
||||
* @param failureCode the sanitized failure code
|
||||
* @param now the current instant
|
||||
*/
|
||||
void markFailed(MessageId messageId, String failureCode, Instant now);
|
||||
|
||||
/**
|
||||
* Releases a lease without changing the record's outcome.
|
||||
*
|
||||
* @param messageId the record identity
|
||||
*/
|
||||
void releaseLease(MessageId messageId);
|
||||
|
||||
/**
|
||||
* Finds one record.
|
||||
*
|
||||
* @param messageId the record identity
|
||||
* @return the record when present
|
||||
*/
|
||||
Optional<OutboxRecord> find(MessageId messageId);
|
||||
|
||||
/**
|
||||
* Deletes records published before a cutoff.
|
||||
*
|
||||
* @param publishedBefore the retention cutoff
|
||||
* @return how many rows were removed
|
||||
*/
|
||||
int purgePublishedBefore(Instant publishedBefore);
|
||||
}
|
||||
+27
@@ -0,0 +1,27 @@
|
||||
package dev.caskeleton.messaging.reliability;
|
||||
|
||||
/**
|
||||
* Where an outbox record is in its lifecycle.
|
||||
*
|
||||
* <p>{@link #AMBIGUOUS} is a distinct state rather than a flavour of failure. A record whose
|
||||
* publish timed out may already be on the broker; retrying it is correct, but only under the same
|
||||
* logical message id, and an operator looking at the table needs to be able to tell those rows
|
||||
* apart from ones that definitely never landed.
|
||||
*/
|
||||
public enum OutboxStatus {
|
||||
|
||||
/** Written by the business transaction, not yet picked up by the relay. */
|
||||
PENDING,
|
||||
|
||||
/** Leased by a relay instance and being published. */
|
||||
IN_FLIGHT,
|
||||
|
||||
/** Confirmed by the broker. */
|
||||
PUBLISHED,
|
||||
|
||||
/** The publish outcome was unknown; the broker may hold it. */
|
||||
AMBIGUOUS,
|
||||
|
||||
/** Definitively rejected; will not be retried without intervention. */
|
||||
FAILED
|
||||
}
|
||||
+27
@@ -0,0 +1,27 @@
|
||||
package dev.caskeleton.messaging.reliability;
|
||||
|
||||
import dev.caskeleton.messaging.api.MessageEnvelope;
|
||||
import dev.caskeleton.messaging.api.destination.MessageDestination;
|
||||
|
||||
/**
|
||||
* Enrols a message in the caller's database transaction instead of publishing it.
|
||||
*
|
||||
* <p>The return type is {@code void}, and that is the contract. There is no publish outcome to
|
||||
* report yet: the row is written inside the caller's transaction, so if the transaction rolls back
|
||||
* the message never existed, and if it commits the relay will publish it later. Handing back a
|
||||
* {@code PublishResult} here would be a lie about work that has not happened.
|
||||
*
|
||||
* <p>This is the answer to the dual-write problem. Writing to the database and publishing to the
|
||||
* broker in the same method cannot be made atomic; writing both to the database can.
|
||||
*/
|
||||
public interface ReliableMessagePublisher {
|
||||
|
||||
/**
|
||||
* Stages a message for publication when the current transaction commits.
|
||||
*
|
||||
* @param <T> the payload type
|
||||
* @param destination the logical destination
|
||||
* @param message the envelope to publish, carrying the identity the relay will preserve
|
||||
*/
|
||||
<T> void addToOutbox(MessageDestination<T> destination, MessageEnvelope<T> message);
|
||||
}
|
||||
+29
@@ -0,0 +1,29 @@
|
||||
package dev.caskeleton.messaging.reliability;
|
||||
|
||||
import dev.caskeleton.messaging.api.delivery.MessageDelivery;
|
||||
|
||||
/**
|
||||
* The business work that runs inside the same transaction as the inbox reservation.
|
||||
*
|
||||
* <p>Sharing one transaction is the entire mechanism. If the effect committed separately from the
|
||||
* "I have handled this message" marker, a crash between the two would either replay the effect or
|
||||
* suppress a message that was never handled — and which of those you get would depend on the order
|
||||
* the two commits happened to be written in.
|
||||
*
|
||||
* <p>Implementations must not settle the message, publish, or start their own transaction. The
|
||||
* runtime owns the transaction boundary precisely so that the action cannot accidentally commit
|
||||
* half of it.
|
||||
*
|
||||
* @param <T> the payload type
|
||||
*/
|
||||
@FunctionalInterface
|
||||
public interface TransactionalMessageAction<T> {
|
||||
|
||||
/**
|
||||
* Applies the side effect for one delivery.
|
||||
*
|
||||
* @param delivery the message being handled
|
||||
* @throws Exception when the effect fails, rolling back both it and the inbox reservation
|
||||
*/
|
||||
void apply(MessageDelivery<T> delivery) throws Exception;
|
||||
}
|
||||
Reference in New Issue
Block a user