fix!: 남은 리뷰 항목과 합친 뒤 드러난 결함을 고친다
문제: 앞 커밋 뒤에도 알림·파일 서버 묶음이 합쳐지지 않았고, 포트 다수에 fake와 실제 구현이 함께 통과하는 공유 계약이 없었고, SpotBugs가 신뢰도 HIGH만 봤고, application-core에 관계없는 클래스 묶음 패키지(outbound)가 있었다. 묶음을 합치자 lane·검사가 새로 드러낸 결함도 있었다(JpaOutbox Store가 읽기 전용 트랜잭션에서 이벤트를 조용히 잃음, gRPC admission controller가 public synchronized라 외부 lock에 막힘, 소비자 decode 타입 등록 경로 없음, compose Redis 익명 접근, local-fileserver lane DB 없음). 방법: 리뷰 README 15절에 남은 결정을 모두 적고 그대로 고쳤다. 트랜잭션· 멱등성·발행·notification 포트에 testFixtures 계약 키트를 두고 fake와 PG·Redis 구현이 상속한다(fake 변이로 계약이 잡는지 확인). SpotBugs는 MEDIUM으로 내리고 진짜 결함은 고치고 오탐은 위치·패턴별 이유를 단 제외로 처리했다. 업무 기능 패키지 규칙을 application-core/CLAUDE.md에 정본으로 두고 ArchUnit 2개와 생성 명령이 강제한다. compose Redis는 infra/redis-sdk ACL로 뜬다. 묶음별 결과는 리뷰 README 16절에 있다. 위험·한계: APP_FLYWAY_ENABLED가 dev·prod에도 적용된다. app.security 오타 키가 이제 기동을 막는다. SES 콜백 replay 창 기본값이 1시간이다. 템플릿 패키지 목록은 CLAUDE.md 표와 TemplatePackageOwnership 두 곳에 있고 일치 검사는 없다. 실제 CI runner 실행은 확인하지 못했다. 검증: ci, mainCheck, integrationCheck, -p optional-platforms ci integrationCheck, performanceCheck, releaseCheck(-PgitRevision), verify-compose-profile-contracts(18 lane) 통과. compose lane 실제 기동: local-fileserver, notification ingest·serving·handoff, local-redis, all-adapters(smoke 3개 포함). Refs: docs/reviews/2026-11-01-maturity-review/README.md 15·16절 BREAKING CHANGE: APP_FLYWAY_ENABLED가 dev·prod 프로필에도 적용되고, app.security의 모르는 키는 기동을 거부한다. MessageHandler에 schemaVersions()가 생겨 decode 목록을 handler 선언에서 만든다.
This commit is contained in:
@@ -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<T>` 하나다. 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`)가 확인한다.
|
||||
|
||||
### 복합 키
|
||||
|
||||
|
||||
@@ -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`로 선언한다.** 숨긴다고 타입이
|
||||
|
||||
+22
@@ -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<T> {
|
||||
*/
|
||||
MessageDestination<T> destination();
|
||||
|
||||
/**
|
||||
* The schema versions of {@link #destination()}'s message type that its payload class reads.
|
||||
*
|
||||
* <p>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.
|
||||
*
|
||||
* <p>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<SchemaVersion> schemaVersions() {
|
||||
return Set.of(new SchemaVersion(1));
|
||||
}
|
||||
|
||||
/**
|
||||
* Handles one delivery.
|
||||
*
|
||||
|
||||
+7
@@ -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<T> implements MessageHandler<T> {
|
||||
return delegate.destination();
|
||||
}
|
||||
|
||||
@Override
|
||||
public Set<SchemaVersion> schemaVersions() {
|
||||
return delegate.schemaVersions();
|
||||
}
|
||||
|
||||
@Override
|
||||
public CompletionStage<HandleResult> handle(MessageDelivery<T> delivery) {
|
||||
Objects.requireNonNull(delivery, "delivery must not be null");
|
||||
|
||||
+52
-1
@@ -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.
|
||||
*
|
||||
* <p>A named holder rather than a bare {@code Map} bean, because {@code Map} is not a neutral
|
||||
* injection type in Spring — a {@code Map<K, V>} 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.
|
||||
*
|
||||
* <p>A deployment registers what it <em>publishes</em> as a bean of this type. What it
|
||||
* <em>consumes</em> 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.
|
||||
*
|
||||
* <p>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<MessageContractKey, Class<?>> byKey) {
|
||||
public static MessageContracts none() {
|
||||
return new MessageContracts(Map.of());
|
||||
}
|
||||
|
||||
/**
|
||||
* These contracts plus every contract the given handlers consume.
|
||||
*
|
||||
* <p>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<? extends MessageHandler<?>> handlers) {
|
||||
Map<MessageContractKey, Class<?>> 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);
|
||||
}
|
||||
}
|
||||
|
||||
+8
-10
@@ -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<Boolean> 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 "
|
||||
|
||||
+1
-1
@@ -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;
|
||||
|
||||
+12
-2
@@ -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.
|
||||
*
|
||||
* <p>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<MessageContracts> contracts) {
|
||||
ObjectProvider<MessageContracts> contracts,
|
||||
ObjectProvider<dev.caskeleton.messaging.api.delivery.MessageHandler<?>> 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()));
|
||||
}
|
||||
|
||||
/**
|
||||
|
||||
+126
@@ -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 <T> MessageHandler<T> handler(Class<T> payload, Set<SchemaVersion> versions) {
|
||||
return new MessageHandler<>() {
|
||||
@Override
|
||||
public MessageDestination<T> destination() {
|
||||
return new MessageDestination<>(
|
||||
new DestinationName("order-events"), new MessageType("order.created"), payload);
|
||||
}
|
||||
|
||||
@Override
|
||||
public Set<SchemaVersion> schemaVersions() {
|
||||
return versions;
|
||||
}
|
||||
|
||||
@Override
|
||||
public CompletionStage<HandleResult> handle(MessageDelivery<T> delivery) {
|
||||
return CompletableFuture.completedFuture(HandleResult.success());
|
||||
}
|
||||
};
|
||||
}
|
||||
|
||||
private static MessageHandler<String> handler() {
|
||||
return new MessageHandler<>() {
|
||||
@Override
|
||||
|
||||
Reference in New Issue
Block a user