diff --git a/docs/messaging/outbox-inbox.md b/docs/messaging/outbox-inbox.md index 7167b1e..6ec2d04 100644 --- a/docs/messaging/outbox-inbox.md +++ b/docs/messaging/outbox-inbox.md @@ -4,6 +4,8 @@ > DataSource 위 `JdbcInboxRepository`, `PlatformTransactionManager` 위 `TransactionRunner`)은 > `adapter:inbound:messaging`(`src/adapter/inbound/messaging/README.md`)이 둔다. platform starter는 두 > bean이 있을 때 `IdempotentConsumer`를 만들어 `INBOX_TRANSACTIONAL` destination의 handler를 감싼다. +> 그 leaf는 inbox 마이그레이션(`V1101`)만 자기 history 표로 적용하므로, 아래 "location 추가"는 platform +> outbox를 쓰는 배포의 이야기다. payload decode 목록은 handler bean의 선언으로 만든다. ## 두 패턴이 각각 무엇을 해결하는가 @@ -130,6 +132,9 @@ consume 계약은 `MessageHandler` 하나다. handler를 bean으로 등록하 - `Reject`는 at-most-once destination에서만 버리고, 그 밖에서는 dead letter로 보낸다. 실제 왕복·중복 제거·DLQ는 `MessagingKafkaConsumeQualificationTest`(Kafka + PostgreSQL Testcontainers)가 확인한다. +애플리케이션 경로(앱 outbox relay가 발행 → `adapter:inbound:messaging`이 조립한 inbox와 JPA 트랜잭션 → +handler)의 중복 전달·실패 재처리는 `InboxRedeliveryIntegrationTest`(lane +`messagingInboxRedeliveryIntegrationTest`)가 확인한다. ### 복합 키 diff --git a/messaging/CLAUDE.md b/messaging/CLAUDE.md index 14c58e8..8c8d2ac 100644 --- a/messaging/CLAUDE.md +++ b/messaging/CLAUDE.md @@ -30,6 +30,16 @@ leaf의 정확한 id는 registry에서 읽는다. family는 **디렉터리 이 JDBC이고 SQL은 `jsonb` · `FOR UPDATE SKIP LOCKED` · `ON CONFLICT` · `TIMESTAMPTZ`로 PostgreSQL 전용이다. `jpa`라는 이름은 사용하지 않는 기술을 광고하고, vendor 중립 port가 어디 있는지도 숨겼다. +### 공용 다이제스트 헬퍼를 복사해 두는 이유 (review 2026-11-01 01-11) + +`messaging-admin`(`HmacApprovalVerifier`, `PlanDigest`)과 `messaging-claim-check` +(`ClaimCheckIntegrityGuard`)는 SHA-256·HMAC-SHA256 계산을 자기 안에 둔다. 템플릿의 +`shared-contract` `digest/Sha256`·`HmacSha256`을 쓰지 않는 것은 의도다. 이 family는 이 애플리케이션의 +계층이 아니라 자기 API·SPI·composition을 가진 다른 제품이고(MSG-023 §6.2), `messaging:*` leaf는 +`domain-core`·`application-core`·`shared-contract` 어느 타입에도 의존하지 않는다. 헬퍼 하나 때문에 +registry edge를 주면 그 경계가 깨진다. 복사본을 고칠 때(키 길이 검사, constant-time 비교 등)는 +`shared-contract`의 정본과 같은 규칙인지 함께 본다. + ## Public surface 정책 - **vendor 타입을 public signature에 노출하면 그 의존성은 `api`로 선언한다.** 숨긴다고 타입이 diff --git a/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/MessageHandler.java b/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/MessageHandler.java index 0abdc89..5e3c3c3 100644 --- a/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/MessageHandler.java +++ b/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/MessageHandler.java @@ -1,6 +1,8 @@ package dev.caskeleton.messaging.api.delivery; +import dev.caskeleton.messaging.api.SchemaVersion; import dev.caskeleton.messaging.api.destination.MessageDestination; +import java.util.Set; import java.util.concurrent.CompletionStage; /** @@ -28,6 +30,26 @@ public interface MessageHandler { */ MessageDestination destination(); + /** + * The schema versions of {@link #destination()}'s message type that its payload class reads. + * + *

This declaration is the consumer's whole registration. The platform decodes a delivery only + * against a contract — message type and schema version — it knows the payload class for, and it + * builds that list from the handler beans: each version here, with the destination's message + * type, decodes into the destination's payload class. A service writes no registration code of + * its own, so a handler cannot exist while its messages are dead-lettered as undecodable for want + * of one. + * + *

A version the handler does not name is still refused ({@code SCHEMA_VERSION_NOT_REGISTERED}) + * rather than decoded into a class written for another version. A handler that reads a second + * version says so here when the producer starts sending it. + * + * @return the versions this handler reads; version 1 unless it declares otherwise + */ + default Set schemaVersions() { + return Set.of(new SchemaVersion(1)); + } + /** * Handles one delivery. * diff --git a/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/inbox/InboxMessageHandler.java b/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/inbox/InboxMessageHandler.java index 23c230f..0bd0055 100644 --- a/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/inbox/InboxMessageHandler.java +++ b/messaging/messaging-reliability/src/main/java/dev/caskeleton/messaging/inbox/InboxMessageHandler.java @@ -1,11 +1,13 @@ package dev.caskeleton.messaging.inbox; +import dev.caskeleton.messaging.api.SchemaVersion; import dev.caskeleton.messaging.api.delivery.HandleResult; import dev.caskeleton.messaging.api.delivery.MessageDelivery; import dev.caskeleton.messaging.api.delivery.MessageHandler; import dev.caskeleton.messaging.api.destination.MessageDestination; import java.time.Instant; import java.util.Objects; +import java.util.Set; import java.util.concurrent.CompletableFuture; import java.util.concurrent.CompletionException; import java.util.concurrent.CompletionStage; @@ -71,6 +73,11 @@ public final class InboxMessageHandler implements MessageHandler { return delegate.destination(); } + @Override + public Set schemaVersions() { + return delegate.schemaVersions(); + } + @Override public CompletionStage handle(MessageDelivery delivery) { Objects.requireNonNull(delivery, "delivery must not be null"); diff --git a/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessageContracts.java b/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessageContracts.java index 82f9721..212ac85 100644 --- a/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessageContracts.java +++ b/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessageContracts.java @@ -1,11 +1,17 @@ package dev.caskeleton.messaging.autoconfigure; +import dev.caskeleton.messaging.api.SchemaVersion; +import dev.caskeleton.messaging.api.delivery.MessageHandler; +import dev.caskeleton.messaging.api.destination.MessageDestination; +import dev.caskeleton.messaging.api.error.MessagingConfigurationException; import dev.caskeleton.messaging.schema.MessageContractKey; +import java.util.Collection; +import java.util.LinkedHashMap; import java.util.Map; import java.util.Objects; /** - * What this deployment publishes: message type and schema version to payload class. + * The deployment's message contracts: message type and schema version to payload class. * *

A named holder rather than a bare {@code Map} bean, because {@code Map} is not a neutral * injection type in Spring — a {@code Map} injection point is interpreted as "every bean of @@ -13,6 +19,12 @@ import java.util.Objects; * into something nobody wrote. A holder makes the intent unambiguous to the container and to a * reader. * + *

A deployment registers what it publishes as a bean of this type. What it + * consumes it does not register at all: {@link #withConsumed} adds each handler bean's own + * declaration, so the codec decodes exactly what some handler said it reads (review 2026-11-01 + * 06-08 follow-up). A consumer whose payload type had to be registered here as well was a consumer + * whose messages were dead-lettered as undecodable whenever that second step was forgotten. + * *

Empty is the default and it is fail-closed: no message type can be encoded, and every publish * is refused at preparation. A codec that accepted an unregistered type would serialise whatever * object it was handed onto a topic that consumers compiled against a different shape will read — @@ -32,4 +44,43 @@ public record MessageContracts(Map> byKey) { public static MessageContracts none() { return new MessageContracts(Map.of()); } + + /** + * These contracts plus every contract the given handlers consume. + * + *

A handler names its message type and payload class in {@link MessageHandler#destination()} + * and the schema versions that class reads in {@link MessageHandler#schemaVersions()}; each + * version is one contract. The same contract declared twice with the same class is one entry. + * + * @param handlers the deployment's handler beans + * @return the combined contracts + * @throws MessagingConfigurationException when two declarations give one contract different + * payload classes — the codec holds one class per contract, so one of them would decode every + * message of that type into the wrong shape + */ + public MessageContracts withConsumed(Collection> handlers) { + Map> combined = new LinkedHashMap<>(byKey); + for (MessageHandler handler : handlers) { + MessageDestination destination = handler.destination(); + for (SchemaVersion version : handler.schemaVersions()) { + MessageContractKey key = new MessageContractKey(destination.messageType(), version); + Class declared = destination.payloadType(); + Class existing = combined.putIfAbsent(key, declared); + if (existing != null && !existing.equals(declared)) { + throw new MessagingConfigurationException( + "MESSAGING_CONTRACT_CONFLICT", + "contract " + + key.describe() + + " is declared as " + + existing.getName() + + " and as " + + declared.getName() + + " (handler for destination '" + + destination.name().value() + + "'); one contract decodes into one payload class"); + } + } + } + return new MessageContracts(combined); + } } diff --git a/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationCompiler.java b/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationCompiler.java index 2a24d32..fd46dd1 100644 --- a/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationCompiler.java +++ b/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationCompiler.java @@ -24,7 +24,6 @@ import java.util.Map; import java.util.Objects; import java.util.Optional; import java.util.Set; -import java.util.function.Supplier; /** * Turns the documented configuration into the objects the platform already validates. @@ -222,10 +221,9 @@ public final class MessagingConfigurationCompiler { broker.production(), broker.tlsEnabled(), security.hostnameVerification(), - credential(name, "producer", security.producer(), () -> true), - credential(name, "consumer", security.consumer(), () -> true), - Optional.ofNullable(security.admin()) - .map(admin -> credential(name, "admin", admin, () -> true)), + credential(name, "producer", security.producer()), + credential(name, "consumer", security.consumer()), + Optional.ofNullable(security.admin()).map(admin -> credential(name, "admin", admin)), new DestinationAccessPolicy( destinationNames(security.access().publishable()), destinationNames(security.access().consumable()), @@ -248,11 +246,11 @@ public final class MessagingConfigurationCompiler { } private static BrokerCredentialProfile credential( - String broker, - String role, - BrokerSecuritySettings.Credential credential, - Supplier required) { - if (credential == null && Boolean.TRUE.equals(required.get())) { + String broker, String role, BrokerSecuritySettings.Credential credential) { + // Every role that reaches here is required: the optional admin role is filtered out by its + // caller before the call. A "not required" branch would have nothing to return and fell + // through to dereference the missing credential. + if (credential == null) { throw configurationError( key("security", broker, role), "a configured broker needs a %s credential; the roles are separate so that a compromised " diff --git a/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingEndpoint.java b/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingEndpoint.java index 666cb4e..79f8518 100644 --- a/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingEndpoint.java +++ b/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingEndpoint.java @@ -23,7 +23,7 @@ import org.springframework.boot.actuate.endpoint.annotation.ReadOperation; * re-identification surface too. */ @Endpoint(id = "messaging") -public class MessagingEndpoint { +public final class MessagingEndpoint { private final ValidatedDestinationRegistry registry; private final MessagingAdmissionController admission; diff --git a/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingPublishConfiguration.java b/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingPublishConfiguration.java index 79995f1..471e32e 100644 --- a/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingPublishConfiguration.java +++ b/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingPublishConfiguration.java @@ -98,16 +98,26 @@ public class MessagingPublishConfiguration { * that accepted an unregistered type would serialise whatever object it was handed and put bytes * on a topic that consumers compiled against a different shape will read. * + *

To those the handler beans add what they consume ({@link MessageContracts#withConsumed}): + * the decode list is what the handlers declare, so a service registers nothing to consume. The + * handlers are resolved here, so a handler whose own dependencies reach back to the publisher is + * a dependency cycle, and Spring refuses it at startup naming both beans. + * * @param contracts the declared message contracts, if the deployment registered any + * @param handlers the deployment's message handlers, whose declarations are decoded * @return the registry, defaulting to JSON */ @Bean @ConditionalOnMissingBean(dev.caskeleton.messaging.schema.MessageCodecRegistry.class) public dev.caskeleton.messaging.runtime.RegisteredMessageCodecs messagingCodecs( - ObjectProvider contracts) { + ObjectProvider contracts, + ObjectProvider> handlers) { return dev.caskeleton.messaging.runtime.RegisteredMessageCodecs.of( dev.caskeleton.messaging.schema.json.JacksonMessageCodec.of( - contracts.getIfAvailable(MessageContracts::none).byKey())); + contracts + .getIfAvailable(MessageContracts::none) + .withConsumed(handlers.orderedStream().toList()) + .byKey())); } /** diff --git a/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingConsumeConfigurationTest.java b/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingConsumeConfigurationTest.java index b8471f8..5976624 100644 --- a/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingConsumeConfigurationTest.java +++ b/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingConsumeConfigurationTest.java @@ -1,13 +1,23 @@ package dev.caskeleton.messaging.autoconfigure; import static org.assertj.core.api.Assertions.assertThat; +import static org.assertj.core.api.Assertions.catchThrowable; +import dev.caskeleton.messaging.api.ContentType; import dev.caskeleton.messaging.api.MessageType; +import dev.caskeleton.messaging.api.SchemaVersion; import dev.caskeleton.messaging.api.delivery.HandleResult; import dev.caskeleton.messaging.api.delivery.MessageDelivery; import dev.caskeleton.messaging.api.delivery.MessageHandler; import dev.caskeleton.messaging.api.destination.DestinationName; import dev.caskeleton.messaging.api.destination.MessageDestination; +import dev.caskeleton.messaging.api.error.MessageValidationException; +import dev.caskeleton.messaging.schema.MessageCodec; +import dev.caskeleton.messaging.schema.MessageCodecRegistry; +import dev.caskeleton.messaging.schema.MessageContractKey; +import java.nio.charset.StandardCharsets; +import java.util.Map; +import java.util.Set; import java.util.concurrent.CompletableFuture; import java.util.concurrent.CompletionStage; import org.junit.jupiter.api.DisplayName; @@ -100,6 +110,122 @@ class MessagingConsumeConfigurationTest { .hasMessageContaining("IdempotentConsumer")); } + @Test + @DisplayName("handler bean이 선언한 메시지 타입과 payload class는 따로 등록하지 않아도 decode된다") + void aHandlerBeansDeclaredContractIsDecodedWithoutAnyRegistration() { + // given: a handler for order.created and no MessageContracts bean at all + var consuming = + runner + .withPropertyValues("app.messaging.destinations.order-events.consumer.group=projection") + .withBean( + "ordersHandler", + MessageHandler.class, + () -> handler(OrderCreated.class, Set.of(new SchemaVersion(1)))); + + // when + consuming.run( + context -> { + OrderCreated decoded = + json(context.getBean(MessageCodecRegistry.class)) + .decode( + new MessageType("order.created"), + new SchemaVersion(1), + "{\"orderId\":\"o-1\"}".getBytes(StandardCharsets.UTF_8), + OrderCreated.class); + + // then + assertThat(decoded).isEqualTo(new OrderCreated("o-1")); + }); + } + + @Test + @DisplayName("handler가 선언하지 않은 schema version은 그 class로 decode하지 않고 거부한다") + void aSchemaVersionTheHandlerDoesNotDeclareIsRefused() { + // given: the handler reads version 1 only + var consuming = + runner + .withPropertyValues("app.messaging.destinations.order-events.consumer.group=projection") + .withBean( + "ordersHandler", + MessageHandler.class, + () -> handler(OrderCreated.class, Set.of(new SchemaVersion(1)))); + + // when + consuming.run( + context -> { + Throwable refused = + catchThrowable( + () -> + json(context.getBean(MessageCodecRegistry.class)) + .decode( + new MessageType("order.created"), + new SchemaVersion(2), + "{\"orderId\":\"o-1\"}".getBytes(StandardCharsets.UTF_8), + OrderCreated.class)); + + // then + assertThat(refused) + .isInstanceOf(MessageValidationException.class) + .hasMessageContaining("order.created v2"); + }); + } + + @Test + @DisplayName("등록된 계약과 handler가 같은 type·version에 다른 class를 선언하면 기동을 거부한다") + void aHandlerThatDeclaresAnotherClassForARegisteredContractFailsStartup() { + // given: order.created v1 registered as String, and a handler reading it as OrderCreated + var conflicting = + runner + .withPropertyValues("app.messaging.destinations.order-events.consumer.group=projection") + .withBean( + MessageContracts.class, + () -> + new MessageContracts( + Map.of(MessageContractKey.of("order.created", 1), String.class))) + .withBean( + "ordersHandler", + MessageHandler.class, + () -> handler(OrderCreated.class, Set.of(new SchemaVersion(1)))); + + // when + conflicting.run( + context -> + // then + assertThat(context) + .hasFailed() + .getFailure() + .rootCause() + .hasMessageContaining("order.created v1") + .hasMessageContaining(OrderCreated.class.getName())); + } + + /** The payload a consumer of {@code order.created} reads. */ + record OrderCreated(String orderId) {} + + private static MessageCodec json(MessageCodecRegistry codecs) { + return codecs.find(ContentType.JSON).orElseThrow(); + } + + private static MessageHandler handler(Class payload, Set versions) { + return new MessageHandler<>() { + @Override + public MessageDestination destination() { + return new MessageDestination<>( + new DestinationName("order-events"), new MessageType("order.created"), payload); + } + + @Override + public Set schemaVersions() { + return versions; + } + + @Override + public CompletionStage handle(MessageDelivery delivery) { + return CompletableFuture.completedFuture(HandleResult.success()); + } + }; + } + private static MessageHandler handler() { return new MessageHandler<>() { @Override