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:
+176
@@ -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();
|
||||
}
|
||||
}
|
||||
+124
@@ -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");
|
||||
}
|
||||
}
|
||||
+135
@@ -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()));
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user