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,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;
}