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,86 @@
package dev.caskeleton.messaging.claimcheck;
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.MessageValidationException;
import dev.caskeleton.messaging.reliability.ClaimCheckReference;
import java.nio.charset.StandardCharsets;
import java.time.Instant;
import org.junit.jupiter.api.Test;
class ClaimCheckIntegrityGuardTest {
private static final Instant NOW = Instant.parse("2026-08-10T09:15:00Z");
private static final byte[] PAYLOAD = "a large document".getBytes(StandardCharsets.UTF_8);
private final ClaimCheckIntegrityGuard guard = new ClaimCheckIntegrityGuard();
@Test
void acceptsAPayloadMatchingItsReference() {
ClaimCheckReference reference =
reference(PAYLOAD.length, ClaimCheckIntegrityGuard.sha256(PAYLOAD));
assertThat(guard.verify(reference, PAYLOAD, NOW)).isEqualTo(PAYLOAD);
}
@Test
void rejectsAPayloadWhoseDigestDoesNotMatch() {
ClaimCheckReference reference =
reference(
PAYLOAD.length,
ClaimCheckIntegrityGuard.sha256(
"a different document".getBytes(StandardCharsets.UTF_8)));
assertThatThrownBy(() -> guard.verify(reference, PAYLOAD, NOW))
.isInstanceOf(MessageValidationException.class)
.hasMessageContaining("digest");
}
@Test
void rejectsATruncatedPayloadBeforeHashingIt() {
ClaimCheckReference reference =
reference(PAYLOAD.length + 10, ClaimCheckIntegrityGuard.sha256(PAYLOAD));
assertThatThrownBy(() -> guard.verify(reference, PAYLOAD, NOW))
.isInstanceOf(MessageValidationException.class)
.hasMessageContaining("bytes");
}
@Test
void rejectsAnExpiredReferenceBeforeTheFetchIsTrusted() {
ClaimCheckReference reference =
new ClaimCheckReference(
"payloads/o-1",
PAYLOAD.length,
ClaimCheckIntegrityGuard.sha256(PAYLOAD),
NOW.minusSeconds(1));
assertThatThrownBy(() -> guard.verify(reference, PAYLOAD, NOW))
.isInstanceOf(MessageValidationException.class)
.hasMessageContaining("retention");
}
@Test
void aReferenceRequiresALowercaseHexDigest() {
assertThatThrownBy(
() -> new ClaimCheckReference("payloads/o-1", 5, "NOT-A-DIGEST", NOW.plusSeconds(60)))
.isInstanceOf(IllegalArgumentException.class);
}
@Test
void theVerifiedPayloadIsACopy() {
ClaimCheckReference reference =
reference(PAYLOAD.length, ClaimCheckIntegrityGuard.sha256(PAYLOAD));
byte[] verified = guard.verify(reference, PAYLOAD, NOW);
verified[0] = 'z';
assertThatCode(() -> guard.verify(reference, PAYLOAD, NOW)).doesNotThrowAnyException();
}
private static ClaimCheckReference reference(long sizeBytes, String sha256) {
return new ClaimCheckReference("payloads/o-1", sizeBytes, sha256, NOW.plusSeconds(3600));
}
}
@@ -0,0 +1,168 @@
package dev.caskeleton.messaging.claimcheck;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.messaging.api.error.MessageValidationException;
import dev.caskeleton.messaging.reliability.ClaimCheckReference;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
import java.time.Instant;
import java.util.HashMap;
import java.util.Map;
import java.util.Optional;
import org.junit.jupiter.api.Test;
class ClaimCheckResolverTest {
private static final Instant NOW = Instant.parse("2026-08-10T09:15:00Z");
private static final byte[] PAYLOAD = "{\"orderId\":\"o-1\"}".getBytes(StandardCharsets.UTF_8);
/** An in-memory store that can be made to return the wrong bytes on purpose. */
private static final class FakeStore implements ClaimCheckStore {
private final Map<String, byte[]> objects = new HashMap<>();
private int puts;
@Override
public ClaimCheckReference put(byte[] payload, Duration retention) {
puts++;
String key = "claim/" + puts;
objects.put(key, payload.clone());
return new ClaimCheckReference(
key, payload.length, ClaimCheckIntegrityGuard.sha256(payload), NOW.plus(retention));
}
@Override
public byte[] get(ClaimCheckReference reference) {
return objects.get(reference.storageKey());
}
@Override
public void delete(ClaimCheckReference reference) {
objects.remove(reference.storageKey());
}
void overwrite(String key, byte[] replacement) {
objects.put(key, replacement);
}
int puts() {
return puts;
}
}
private static byte[] filled(int size) {
byte[] payload = new byte[size];
java.util.Arrays.fill(payload, (byte) 'x');
return payload;
}
@Test
void aSmallPayloadTravelsInlineAndIsNeverStored() {
FakeStore store = new FakeStore();
ClaimCheckPublisher publisher = new ClaimCheckPublisher(store, ClaimCheckPolicy.defaults());
ClaimCheckPublisher.Offloaded offloaded = publisher.offload(PAYLOAD);
assertThat(offloaded.isOffloaded()).isFalse();
assertThat(store.puts()).isZero();
}
@Test
void aLargePayloadIsStoredAndTheMessageCarriesNoBytes() {
FakeStore store = new FakeStore();
ClaimCheckPublisher publisher = new ClaimCheckPublisher(store, ClaimCheckPolicy.defaults());
ClaimCheckPublisher.Offloaded offloaded =
publisher.offload(filled(ClaimCheckPolicy.DEFAULT_THRESHOLD_BYTES + 1));
assertThat(offloaded.isOffloaded()).isTrue();
assertThat(offloaded.payload().length)
.as("carrying both would double the transfer and let the two disagree")
.isZero();
}
@Test
void anOffloadedPayloadRoundTripsThroughTheStore() {
FakeStore store = new FakeStore();
ClaimCheckPolicy policy =
new ClaimCheckPolicy(8, Duration.ofDays(3), Duration.ofDays(1), Duration.ofDays(1));
ClaimCheckPublisher.Offloaded offloaded =
new ClaimCheckPublisher(store, policy).offload(PAYLOAD);
byte[] resolved =
new ClaimCheckResolver(store).resolve(offloaded.payload(), offloaded.reference(), NOW);
assertThat(resolved).isEqualTo(PAYLOAD);
}
@Test
void anInlinePayloadIsReturnedWithoutTouchingTheStore() {
FakeStore store = new FakeStore();
byte[] resolved = new ClaimCheckResolver(store).resolve(PAYLOAD, Optional.empty(), NOW);
assertThat(resolved).isEqualTo(PAYLOAD);
}
@Test
void anObjectThatWasSwappedUnderTheReferenceIsAPoisonMessage() {
FakeStore store = new FakeStore();
ClaimCheckPolicy policy =
new ClaimCheckPolicy(8, Duration.ofDays(3), Duration.ofDays(1), Duration.ofDays(1));
ClaimCheckPublisher.Offloaded offloaded =
new ClaimCheckPublisher(store, policy).offload(PAYLOAD);
store.overwrite(
offloaded.reference().orElseThrow().storageKey(),
"{\"orderId\":\"SOMEONE-ELSE\"}".getBytes(StandardCharsets.UTF_8));
assertThatThrownBy(
() ->
new ClaimCheckResolver(store)
.resolve(offloaded.payload(), offloaded.reference(), NOW))
.as("the digest is the only thing between a swapped object and the wrong data")
.isInstanceOf(ClaimCheckIntegrityException.class);
}
@Test
void anIntegrityFailureIsNotRetryableBecauseTheKeyReturnsTheSameBytes() {
ClaimCheckIntegrityException failure =
new ClaimCheckIntegrityException("CLAIM_CHECK_DIGEST_MISMATCH", "swapped");
assertThat(failure.failure().retryable()).isFalse();
}
@Test
void amissingObjectIsReportedSeparatelyFromASwappedOne() {
FakeStore store = new FakeStore();
ClaimCheckPolicy policy =
new ClaimCheckPolicy(8, Duration.ofDays(3), Duration.ofDays(1), Duration.ofDays(1));
ClaimCheckPublisher.Offloaded offloaded =
new ClaimCheckPublisher(store, policy).offload(PAYLOAD);
store.delete(offloaded.reference().orElseThrow());
assertThatThrownBy(
() ->
new ClaimCheckResolver(store)
.resolve(offloaded.payload(), offloaded.reference(), NOW))
.isInstanceOf(MessageValidationException.class)
.hasMessageContaining("never written");
}
@Test
void anExpiredReferenceIsRefusedBeforeTheStoreIsEvenAsked() {
FakeStore store = new FakeStore();
ClaimCheckReference expired =
new ClaimCheckReference(
"claim/1",
PAYLOAD.length,
ClaimCheckIntegrityGuard.sha256(PAYLOAD),
NOW.minus(Duration.ofHours(1)));
assertThatThrownBy(
() -> new ClaimCheckResolver(store).resolve(new byte[0], Optional.of(expired), NOW))
.isInstanceOf(MessageValidationException.class)
.hasMessageContaining("expired");
}
}
@@ -0,0 +1,79 @@
package dev.caskeleton.messaging.claimcheck;
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.MessagingConfigurationException;
import java.time.Duration;
import org.junit.jupiter.api.Test;
class ClaimCheckRetentionValidatorTest {
@Test
void retentionShorterThanTheMessageLifetimeIsRefused() {
assertThatThrownBy(
() ->
new ClaimCheckPolicy(
1024, Duration.ofHours(6), Duration.ofDays(1), Duration.ofDays(1)))
.as("the object would be reaped while a consumer can still be handed its message")
.isInstanceOf(MessagingConfigurationException.class)
.hasMessageContaining("reaped");
}
@Test
void retentionCoveringBrokerRetentionPlusTheRetryPathIsAccepted() {
assertThatCode(
() ->
new ClaimCheckPolicy(
1024, Duration.ofDays(2), Duration.ofDays(1), Duration.ofDays(1)))
.doesNotThrowAnyException();
}
@Test
void theRequiredRetentionIsBrokerRetentionPlusTheRedeliveryWindow() {
ClaimCheckPolicy policy =
new ClaimCheckPolicy(1024, Duration.ofDays(5), Duration.ofDays(2), Duration.ofDays(1));
assertThat(policy.requiredRetention()).isEqualTo(Duration.ofDays(3));
}
@Test
void theDefaultsSatisfyTheirOwnRule() {
assertThatCode(ClaimCheckPolicy::defaults).doesNotThrowAnyException();
}
/** The portable payload limit the platform documents, restated here so the two cannot drift. */
private static final int PORTABLE_PAYLOAD_LIMIT_BYTES = 1_048_576;
@Test
void theOffloadThresholdSitsWellBelowThePortablePayloadLimit() {
assertThat(ClaimCheckPolicy.DEFAULT_THRESHOLD_BYTES)
.as(
"offloading starts where carrying inline stops being wise, not where the broker refuses")
.isLessThan(PORTABLE_PAYLOAD_LIMIT_BYTES);
}
@Test
void aPayloadAtTheThresholdStillTravelsInline() {
ClaimCheckPolicy policy = ClaimCheckPolicy.defaults();
assertThat(policy.shouldOffload(ClaimCheckPolicy.DEFAULT_THRESHOLD_BYTES)).isFalse();
assertThat(policy.shouldOffload(ClaimCheckPolicy.DEFAULT_THRESHOLD_BYTES + 1)).isTrue();
}
@Test
void aNonPositiveDurationIsRefused() {
assertThatThrownBy(
() -> new ClaimCheckPolicy(1024, Duration.ZERO, Duration.ofDays(1), Duration.ofDays(1)))
.isInstanceOf(IllegalArgumentException.class);
}
@Test
void aNonPositiveThresholdIsRefused() {
assertThatThrownBy(
() ->
new ClaimCheckPolicy(0, Duration.ofDays(3), Duration.ofDays(1), Duration.ofDays(1)))
.isInstanceOf(IllegalArgumentException.class);
}
}