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:
DongHyeonka
2026-08-14 14:55:38 +09:00
parent 432130fd62
commit e23ed9486e
475 changed files with 39748 additions and 0 deletions
@@ -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
@@ -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);
}
}
@@ -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);
}
@@ -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");
}
}
}
@@ -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);
}
@@ -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;
}
}
@@ -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
+ "]";
}
}
@@ -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);
}
@@ -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
}
@@ -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);
}
@@ -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;
}