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:
+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