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,176 @@
package dev.caskeleton.messaging.schema.json;
import dev.caskeleton.messaging.api.ContentType;
import dev.caskeleton.messaging.api.MessageType;
import dev.caskeleton.messaging.api.SchemaVersion;
import dev.caskeleton.messaging.api.error.MessageSerializationException;
import dev.caskeleton.messaging.api.error.MessageTooLargeException;
import dev.caskeleton.messaging.api.error.MessageValidationException;
import dev.caskeleton.messaging.schema.EncodedMessage;
import dev.caskeleton.messaging.schema.MessageCodec;
import dev.caskeleton.messaging.schema.SchemaReference;
import java.util.Map;
import java.util.Objects;
import java.util.Optional;
import tools.jackson.core.JacksonException;
import tools.jackson.core.StreamReadConstraints;
import tools.jackson.core.StreamReadFeature;
import tools.jackson.core.json.JsonFactory;
import tools.jackson.databind.DeserializationFeature;
import tools.jackson.databind.ObjectMapper;
import tools.jackson.databind.json.JsonMapper;
/**
* The Stable JSON codec.
*
* <p>Three things make this safe to expose as the default. The message-type registry is closed, so
* a payload class only becomes reachable when someone registered it. The parser is constrained on
* depth, document length, and duplicate keys, so a hostile document cannot exhaust the consumer
* before the handler ever runs. And the encoded size is checked against the destination limit here
* rather than at the broker, so an oversized payload fails locally with {@code NOT_TRANSMITTED}
* evidence instead of ambiguously mid-flight.
*
* <p>Polymorphic default typing is never enabled. It is the mechanism behind most JSON
* deserialization gadget chains, and no legitimate message contract needs it.
*/
public final class JacksonMessageCodec implements MessageCodec {
/** The portability limit shared with the other Stable codecs. */
public static final int DEFAULT_MAX_BYTES = 1_048_576;
/** The parser nesting depth ceiling. */
public static final int MAX_NESTING_DEPTH = 100;
private static final int MAX_STRING_CHARACTERS = 5_000_000;
private static final int MAX_NUMBER_DIGITS = 1_000;
private final ObjectMapper mapper;
private final Map<MessageType, Class<?>> registry;
private final int maxBytes;
private JacksonMessageCodec(Map<MessageType, Class<?>> registry, int maxBytes) {
this.registry = Map.copyOf(registry);
this.maxBytes = maxBytes;
this.mapper = strictMapper(maxBytes);
}
/**
* Creates a codec over an explicit message-type registry.
*
* @param registry the closed map of message type to payload class
* @return a codec with the default one mebibyte limit
*/
public static JacksonMessageCodec of(Map<MessageType, Class<?>> registry) {
return new JacksonMessageCodec(registry, DEFAULT_MAX_BYTES);
}
/**
* Creates a codec over an explicit registry and byte limit.
*
* @param registry the closed map of message type to payload class
* @param maxBytes the maximum encoded size
* @return a codec
*/
public static JacksonMessageCodec of(Map<MessageType, Class<?>> registry, int maxBytes) {
return new JacksonMessageCodec(registry, maxBytes);
}
/**
* Creates a single-entry codec for focused tests.
*
* @param type the catalog message type
* @param payloadType the payload class
* @return a codec registering exactly one type
*/
public static JacksonMessageCodec testingDefault(MessageType type, Class<?> payloadType) {
return new JacksonMessageCodec(Map.of(type, payloadType), DEFAULT_MAX_BYTES);
}
@Override
public ContentType contentType() {
return ContentType.JSON;
}
@Override
public EncodedMessage encode(MessageType type, SchemaVersion version, Object payload) {
Class<?> registered = requireRegistered(type);
Objects.requireNonNull(version, "schemaVersion must not be null");
Objects.requireNonNull(payload, "payload must not be null");
if (!registered.isInstance(payload)) {
throw new MessageValidationException(
"PAYLOAD_TYPE_MISMATCH",
"payload does not match the registered type for " + type.value());
}
byte[] bytes;
try {
bytes = mapper.writeValueAsBytes(payload);
} catch (JacksonException exception) {
throw new MessageSerializationException(
"JSON_ENCODE_FAILED", "payload could not be encoded as JSON", exception);
}
if (bytes.length > maxBytes) {
throw new MessageTooLargeException(
"PAYLOAD_TOO_LARGE",
"encoded payload is " + bytes.length + " bytes, limit is " + maxBytes);
}
return new EncodedMessage(
bytes, ContentType.JSON, Optional.of(SchemaReference.of(type.value(), version)));
}
@Override
public <T> T decode(
MessageType type, SchemaVersion version, byte[] encoded, Class<T> payloadType) {
Class<?> registered = requireRegistered(type);
Objects.requireNonNull(version, "schemaVersion must not be null");
Objects.requireNonNull(encoded, "encoded bytes must not be null");
Objects.requireNonNull(payloadType, "payloadType must not be null");
if (!registered.equals(payloadType)) {
throw new MessageValidationException(
"PAYLOAD_TYPE_MISMATCH",
"requested type does not match the registered type for " + type.value());
}
if (encoded.length > maxBytes) {
throw new MessageTooLargeException(
"PAYLOAD_TOO_LARGE",
"encoded payload is " + encoded.length + " bytes, limit is " + maxBytes);
}
try {
return mapper.readValue(encoded, payloadType);
} catch (JacksonException exception) {
throw new MessageSerializationException(
"JSON_DECODE_FAILED", "payload could not be decoded as JSON", exception);
}
}
private Class<?> requireRegistered(MessageType type) {
Objects.requireNonNull(type, "messageType must not be null");
Class<?> registered = registry.get(type);
if (registered == null) {
throw new MessageValidationException(
"UNKNOWN_MESSAGE_TYPE", "message type is not registered: " + type.value());
}
return registered;
}
private static ObjectMapper strictMapper(int maxBytes) {
JsonFactory factory =
JsonFactory.builder()
.streamReadConstraints(
StreamReadConstraints.builder()
.maxNestingDepth(MAX_NESTING_DEPTH)
.maxDocumentLength(maxBytes)
.maxNumberLength(MAX_NUMBER_DIGITS)
.maxStringLength(MAX_STRING_CHARACTERS)
.maxNameLength(MAX_STRING_CHARACTERS)
.build())
.enable(StreamReadFeature.STRICT_DUPLICATE_DETECTION)
.build();
return JsonMapper.builder(factory)
.enable(DeserializationFeature.FAIL_ON_READING_DUP_TREE_KEY)
.enable(DeserializationFeature.FAIL_ON_TRAILING_TOKENS)
.enable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES)
.build();
}
}
@@ -0,0 +1,124 @@
package dev.caskeleton.messaging.schema.json;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.messaging.api.MessageType;
import dev.caskeleton.messaging.api.SchemaVersion;
import dev.caskeleton.messaging.api.error.MessageSerializationException;
import dev.caskeleton.messaging.api.error.MessageTooLargeException;
import dev.caskeleton.messaging.api.error.MessageValidationException;
import java.nio.charset.StandardCharsets;
import org.junit.jupiter.api.Test;
class JacksonMessageCodecTest {
private static final MessageType ORDER_CREATED = new MessageType("order.created");
private static final SchemaVersion V1 = new SchemaVersion(1);
record OrderCreated(String orderId, long amount) {}
@Test
void roundTripsRegisteredType() {
JacksonMessageCodec codec =
JacksonMessageCodec.testingDefault(ORDER_CREATED, OrderCreated.class);
byte[] encoded = codec.encode(ORDER_CREATED, V1, new OrderCreated("o-1", 1000)).bytes();
assertThat(codec.decode(ORDER_CREATED, V1, encoded, OrderCreated.class))
.isEqualTo(new OrderCreated("o-1", 1000));
}
@Test
void rejectsPayloadOverOneMibibyte() {
JacksonMessageCodec codec =
JacksonMessageCodec.testingDefault(new MessageType("text.large"), String.class);
String value = "a".repeat(1_048_577);
assertThatThrownBy(() -> codec.encode(new MessageType("text.large"), V1, value))
.isInstanceOf(MessageTooLargeException.class)
.hasMessageContaining("1048576");
}
@Test
void rejectsUnregisteredMessageType() {
JacksonMessageCodec codec =
JacksonMessageCodec.testingDefault(ORDER_CREATED, OrderCreated.class);
assertThatThrownBy(
() -> codec.encode(new MessageType("order.cancelled"), V1, new OrderCreated("o", 1)))
.isInstanceOf(MessageValidationException.class)
.hasMessageContaining("not registered");
}
@Test
void rejectsPayloadThatDoesNotMatchTheRegisteredType() {
JacksonMessageCodec codec =
JacksonMessageCodec.testingDefault(ORDER_CREATED, OrderCreated.class);
assertThatThrownBy(() -> codec.encode(ORDER_CREATED, V1, "not an order"))
.isInstanceOf(MessageValidationException.class);
}
@Test
void rejectsTrailingDataAfterTheDocument() {
JacksonMessageCodec codec =
JacksonMessageCodec.testingDefault(ORDER_CREATED, OrderCreated.class);
byte[] trailing =
"{\"orderId\":\"o-1\",\"amount\":1} {\"orderId\":\"o-2\",\"amount\":2}"
.getBytes(StandardCharsets.UTF_8);
assertThatThrownBy(() -> codec.decode(ORDER_CREATED, V1, trailing, OrderCreated.class))
.isInstanceOf(MessageSerializationException.class);
}
@Test
void rejectsUnknownProperties() {
JacksonMessageCodec codec =
JacksonMessageCodec.testingDefault(ORDER_CREATED, OrderCreated.class);
byte[] extra =
"{\"orderId\":\"o-1\",\"amount\":1,\"injected\":true}".getBytes(StandardCharsets.UTF_8);
assertThatThrownBy(() -> codec.decode(ORDER_CREATED, V1, extra, OrderCreated.class))
.isInstanceOf(MessageSerializationException.class);
}
@Test
void rejectsDuplicateKeys() {
JacksonMessageCodec codec =
JacksonMessageCodec.testingDefault(ORDER_CREATED, OrderCreated.class);
byte[] duplicate =
"{\"orderId\":\"o-1\",\"orderId\":\"o-2\",\"amount\":1}".getBytes(StandardCharsets.UTF_8);
assertThatThrownBy(() -> codec.decode(ORDER_CREATED, V1, duplicate, OrderCreated.class))
.isInstanceOf(MessageSerializationException.class);
}
@Test
void rejectsNestingBeyondTheDepthCeiling() {
JacksonMessageCodec codec =
JacksonMessageCodec.testingDefault(new MessageType("deep.doc"), Object.class);
String deep = "[".repeat(200) + "]".repeat(200);
assertThatThrownBy(
() ->
codec.decode(
new MessageType("deep.doc"),
V1,
deep.getBytes(StandardCharsets.UTF_8),
Object.class))
.isInstanceOf(MessageSerializationException.class);
}
@Test
void encodedMessageCarriesTheSchemaReference() {
JacksonMessageCodec codec =
JacksonMessageCodec.testingDefault(ORDER_CREATED, OrderCreated.class);
var encoded = codec.encode(ORDER_CREATED, V1, new OrderCreated("o-1", 1000));
assertThat(encoded.schemaReference()).isPresent();
assertThat(encoded.schemaReference().orElseThrow().subject()).isEqualTo("order.created");
assertThat(encoded.contentType().value()).isEqualTo("application/json");
}
}
@@ -0,0 +1,135 @@
package dev.caskeleton.messaging.schema.json;
import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.messaging.api.ContentType;
import dev.caskeleton.messaging.api.MessageEnvelope;
import dev.caskeleton.messaging.api.MessageId;
import dev.caskeleton.messaging.api.MessageType;
import dev.caskeleton.messaging.api.ProducerId;
import dev.caskeleton.messaging.api.SchemaVersion;
import dev.caskeleton.messaging.api.TraceContext;
import dev.caskeleton.messaging.api.header.MessageHeaders;
import dev.caskeleton.messaging.schema.EncodedMessage;
import java.time.Duration;
import java.time.Instant;
import java.util.Optional;
import org.junit.jupiter.api.Test;
/**
* Bounds the platform's own per-message cost.
*
* <p>This measures what the platform adds — identity, validation, encoding — and nothing else.
* There is no broker in the loop, deliberately: broker throughput is a property of the deployment
* and varies by an order of magnitude between a laptop and a cluster, so asserting on it produces a
* test that fails for reasons nobody can act on.
*
* <p>The budgets are generous on purpose. The regression worth catching here is structural — an
* accidental per-message reflection call, a defensive copy that became a deep copy, a validator
* that started compiling a regex per invocation — and those cost orders of magnitude, not
* percentages. A tight budget would instead catch a busy CI agent.
*/
class PlatformOverheadPerformanceTest {
private static final MessageType ORDER_CREATED = new MessageType("order.created");
private static final SchemaVersion V1 = new SchemaVersion(1);
private static final Instant NOW = Instant.parse("2026-08-10T09:15:00Z");
private static final int WARMUP = 5_000;
private static final int MEASURED = 50_000;
/** Generous enough that only a structural regression trips it. */
private static final Duration ENVELOPE_BUDGET_PER_MESSAGE = Duration.ofNanos(20_000);
private static final Duration ENCODE_BUDGET_PER_MESSAGE = Duration.ofNanos(50_000);
record OrderCreated(String orderId, long amount) {}
@Test
void envelopeConstructionStaysWellUnderItsBudget() {
for (int i = 0; i < WARMUP; i++) {
envelope(new byte[64]);
}
long startedAt = System.nanoTime();
for (int i = 0; i < MEASURED; i++) {
envelope(new byte[64]);
}
Duration perMessage = Duration.ofNanos((System.nanoTime() - startedAt) / MEASURED);
assertThat(perMessage)
.as("envelope construction per message: %s", perMessage)
.isLessThan(ENVELOPE_BUDGET_PER_MESSAGE);
}
@Test
void jsonEncodingStaysWellUnderItsBudget() {
JacksonMessageCodec codec =
JacksonMessageCodec.testingDefault(ORDER_CREATED, OrderCreated.class);
OrderCreated payload = new OrderCreated("o-1", 1000);
for (int i = 0; i < WARMUP; i++) {
codec.encode(ORDER_CREATED, V1, payload);
}
long startedAt = System.nanoTime();
for (int i = 0; i < MEASURED; i++) {
codec.encode(ORDER_CREATED, V1, payload);
}
Duration perMessage = Duration.ofNanos((System.nanoTime() - startedAt) / MEASURED);
assertThat(perMessage)
.as("JSON encode per message: %s", perMessage)
.isLessThan(ENCODE_BUDGET_PER_MESSAGE);
}
@Test
void aRoundTripDoesNotAllocateAGrowingRetainedSet() {
JacksonMessageCodec codec =
JacksonMessageCodec.testingDefault(ORDER_CREATED, OrderCreated.class);
OrderCreated payload = new OrderCreated("o-1", 1000);
for (int i = 0; i < WARMUP; i++) {
byte[] encoded = codec.encode(ORDER_CREATED, V1, payload).bytes();
codec.decode(ORDER_CREATED, V1, encoded, OrderCreated.class);
}
Runtime runtime = Runtime.getRuntime();
System.gc();
long before = runtime.totalMemory() - runtime.freeMemory();
for (int i = 0; i < MEASURED; i++) {
byte[] encoded = codec.encode(ORDER_CREATED, V1, payload).bytes();
codec.decode(ORDER_CREATED, V1, encoded, OrderCreated.class);
}
System.gc();
long after = runtime.totalMemory() - runtime.freeMemory();
long retainedPerMessage = Math.max(0, after - before) / MEASURED;
assertThat(retainedPerMessage)
.as(
"the codec must not retain per-message state; retained %d bytes/message",
retainedPerMessage)
.isLessThan(64);
}
private static MessageEnvelope<EncodedMessage> envelope(byte[] payload) {
return new MessageEnvelope<>(
MessageId.newId(),
ORDER_CREATED,
V1,
NOW,
Optional.of(NOW),
new ProducerId("order-api"),
Optional.empty(),
Optional.empty(),
ContentType.JSON,
Optional.of("acct-1"),
Optional.of("acct-1"),
Optional.empty(),
TraceContext.none(),
MessageHeaders.empty(),
new EncodedMessage(payload, ContentType.JSON, Optional.empty()));
}
}