adapter:inbound:messaging — 이벤트 소비 경로
- Module ID:
adapter-inbound-messaging - Gradle path:
:adapter:inbound:messaging - Package:
dev.caskeleton.adapter.inbound.messaging - 테스트:
./gradlew :adapter:inbound:messaging:test --console=plain - 실제 Kafka + PostgreSQL lane:
./gradlew :adapter:inbound:messaging:messagingInboxRedeliveryIntegrationTest --console=plain(:integrationCheck에 포함, Docker 필요)
제공하는 것
소유자 결정 10("Kafka 소비 지원")을 application 쪽까지 잇는 최소 경로다(리뷰 2026-11-01 06-08).
Kafka ─▶ platform consumer (starter-kafka)
└─ INBOX_TRANSACTIONAL destination이면
InboxMessageHandler ─▶ IdempotentConsumer.runOnce (platform이 감싼다)
├─ JdbcInboxRepository.reserve ← 이 leaf가 조립
└─ 애플리케이션 MessageHandler ─▶ use case
(같은 PlatformTransactionManager 트랜잭션) ← 이 leaf가 조립
MessagingInboxAutoConfiguration:MessageHandlerbean과DataSource·PlatformTransactionManager가 있을 때만, platform inbox가 요구하는 두 부품을 만든다.JdbcInboxRepository(애플리케이션 DataSource).DataSourceUtils로 연결을 얻으므로 runner가 연 트랜잭션에 참여한다.IdempotentConsumer.TransactionRunner(애플리케이션PlatformTransactionManager위의TransactionTemplate). inbox 예약과 use case의 JPA 쓰기가 한 트랜잭션에서 함께 커밋되거나 함께 롤백된다. handler가 실패하면 예약도 롤백되어 재전달이 효과를 다시 적용한다.
- platform starter(
MessagingReliabilityAutoConfiguration)가 이 두 bean으로IdempotentConsumer를 만든다. platform은 애플리케이션의 datasource·트랜잭션을 스스로 고르지 않는다는 기존 설계를 그대로 둔다. - 애플리케이션의 handler(
MessageHandler<T>구현)는 이 leaf에 둔다. 컨트롤러가 HTTP 요청을 use case 호출로 바꾸듯 delivery를 use case 호출 하나로 바꾸는 inbound adapter다. 업무 규칙은 use case에 둔다. - 쓰기 use case를 부르는 handler는
@SystemCaller(reason = ...)이고,@SystemInvokeduse case를 생성자에서new로 만들어 혼자 든다. use case는 bean이 아니다. 소비 스레드에는 인증이 없어@RequiresPermissionuse case는 매번 거부되기 때문이다. 작업 순서는docs/manual/09-outbox-events.md「소비」 4단계, 규칙은 07장 「시스템이 부르는 쓰기」(리뷰 2026-11-03 RR-01-12, 결정 9.1).
추가할 한 줄
// app-bootstrap/build.gradle — 기본 조립에는 없다
runtimeOnly project(':adapter:inbound:messaging') // 이벤트 소비 + inbox
adapter:outbound:messaging-kafka 줄(broker·platform)과 persistence-jpa(DataSource·트랜잭션)가 함께
있어야 한다. registry의 app-bootstrap 간선에 이 leaf(adapter-inbound-messaging)가 있어서 이 줄은 방향
gate를 통과한다.
이 leaf의 Gradle 좌표는 dev.caskeleton.adapter.inbound:adapter-inbound-messaging이다. 프로젝트 이름이
발행 bridge(:adapter:outbound:messaging)와 같아서, 기본 group이면 두 프로젝트가 같은 모듈로 취급돼
Gradle이 하나를 조용히 뺐다(relay가 발행 포트를 잃었다). build.gradle이 group과 jar 이름을 따로 둔다.
서비스가 따로 쓰는 코드는 handler뿐이다. 아래 둘은 이 줄을 넣으면 따라온다.
- payload decode 등록: platform consumer는 (메시지 타입, schema version) → payload class 목록에 있는
것만 decode한다. 그 목록을 handler bean의 선언으로 만든다 —
destination()의 메시지 타입·payload class와schemaVersions()(기본 v1). starter의MessageContracts에 소비 타입을 등록하는 코드는 쓰지 않는다. 등록을 빠뜨린 handler는 메시지를PAYLOAD_UNDECODABLE로 DLQ에 보내 효과 없이 끝났다. 같은 (타입, 버전)에 발행 등록(MessageContracts)과 다른 class를 선언하면 기동이MESSAGING_CONTRACT_CONFLICT로 실패한다. - inbox 테이블:
messaging_inbox는 platform의messaging-reliability-jdbc-postgresqldb/migration/messaging/V1101__messaging_inbox.sql이 만든다.MessagingInboxSchemaStream이 기동 중 (모든 singleton 생성 뒤, consumer 시작 전) 이 마이그레이션을 history 표flyway_messaging_inbox_history로 적용한다. 같은 위치의 platform outbox 대역(V1001..V1099)은 baseline1100으로 건너뛰고,1199까지만 올린다 — 애플리케이션은 자기 outbox가 있어 platform outbox 표를 만들지 않는다.app.runtime.migration-on-startup=false이면(다른 stream과 같은 스위치) 운영자가 V1101을 직접 적용한다.- 버린 대안:
db/migration/messaging을 기본 Flyway location에 추가. V1101이flyway_schema_history에 들어가면 애플리케이션의 다음 마이그레이션(V22)이 적용된 버전보다 낮아져 out-of-order로 거부된다.
- 버린 대안:
destination 예시
app:
messaging:
destinations:
order-events:
broker: kafka
kind: EVENT_STREAM
physical:
topic: order.events.v1
schema:
message-types: [order.created]
guarantees:
delivery: AT_LEAST_ONCE
external-side-effect: INBOX_TRANSACTIONAL # handler를 inbox로 감싼다
consumer:
group: order-projection # inbox의 consumer identity
dlq:
destination: order-events-dlq
handler 예시: 쓰기 use case를 부르는 모양은 SystemInvokedConsumePathTest의 OrderCreatedHandler, 실제 Kafka +
PostgreSQL에서 같은 모양은 InboxRedeliveryIntegrationTest의 ProjectionHandler다.
고른 방법과 버린 대안
- 고름: platform은
InboxRepository+TransactionRunnerbean이 있을 때만IdempotentConsumer를 만들고, 두 부품은 이 application leaf가 준다. platform 경계(애플리케이션 datasource를 고르지 않음)와 registry 간선(messaging은 messaging만 의존)이 그대로다. - 버림: app-bootstrap에서 handler·inbox를 직접 등록 — composition root에 업무 handler가 들어간다 (HARD-STOP 4).
- 버림:
adapter:outbound:messaging(발행 bridge)에 소비까지 넣기 — 발행 bridge는messaging-core-api만 보는 anti-corruption 경계이고, 소비는 inbound 방향이다. - 고름(RR-01-12): handler가
@SystemCaller를 달고@SystemInvokeduse case를 직접new로 만든다. 사용자 요청이 들어오는 전송(web·GraphQL·gRPC·WebSocket)만 그 use case에 닿지 못하고, 표시는 ArchUnit이 검사한다 (SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS: 표시한 클래스와 그 안에 중첩된 클래스는 messaging· scheduler inbound 패키지에만, 사용자 전송 타입에 의존하지 않음). 사용자 전송이 handler bean을 주입받아 부르는 길은USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS가 막는다(RR3-01-01). handler가 구현하는MessageHandler<T>같은 프로젝트 인터페이스로 주입받아도 같다. handler는 프로젝트 밖 타입(Runnable등)을 구현하지 않는다(SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES, RR4-01-01). 기동 가드는 바꾸지 않는다:@SystemInvokedbean은 예외 없이 실패다. 규칙 전체는 매뉴얼 07장 「시스템이 부르는 쓰기」.- 버림: use case를 bean으로 두고 가드에 "handler만 주입받으면 허용" 예외 — 누가 주입받는지는 기동 때
확정되지 않는다(
ObjectProvider,getBean, 나중에 추가된 bean). 예외 조건이 곧 우회 경로가 된다. - 버림: handler는
CommandUseCase인터페이스만 받고 조립 모듈이new로 넣기 — 소비자마다 composition 모듈이 필요하거나 app-bootstrap에 업무 조립이 들어간다(위 HARD-STOP 4). 조립 클래스도 결국 그 use case 클래스에 의존한다. - 버림: ArchUnit 대상에서 messaging 패키지를 통째로 빼기 — 클래스에 표시가 없어 의도가 안 보이고, 그 패키지의 아무 클래스(HTTP endpoint 포함)나 닿는다.
- 버림: 사용자 전송 패키지만 나열해 금지 — 나중에 새 전송이 생기면 조용히 열린다. 규칙은 "닿아도 되는
쪽"을 적는다. 이 성질은 패키지 쪽에만 있다: 시스템 패키지 안에 놓인 endpoint를 알아보는 사용자 전송
타입은 나열 목록이다(
ARE_USER_TRANSPORT_TYPES, JAX-RS·graphql-java 포함). 새 전송 라이브러리를 들이면 그 목록에 더한다(RR3-01-02).
- 버림: use case를 bean으로 두고 가드에 "handler만 주입받으면 허용" 예외 — 누가 주입받는지는 기동 때
확정되지 않는다(
- 버림: application-core에 소비 포트를 새로 만들어 platform
MessageHandler로 감싸는 범용 bridge — payload 타입 매핑과 결과 매핑 규칙을 먼저 정해야 해서 이번 범위보다 크다. 지금은 handler가 직접 use case를 부른다.
검증
- 단위:
MessagingInboxAutoConfigurationTest— 조립 조건, inbox 마이그레이션 stream 조립 스위치, runner의 커밋·롤백, in-memory inbox로 중복 1회. decode 목록은 starterMessagingConsumeConfigurationTest. - 단위:
SystemInvokedConsumePathTest— 이 leaf의 inbox와composition:service-runtime의 권한 가드를 함께 띄워,@SystemCallerhandler가 만든@SystemInvokeduse case로 기동하고 같은 delivery 두 번에 쓰기가 한 번인지, use case를 bean으로 두면 기동이 실패하는지 본다. - 실제 Kafka + PostgreSQL:
InboxRedeliveryIntegrationTest(lanemessagingInboxRedeliveryIntegrationTest). Kafka capability, outbox relay, persistence-jpa, 이 leaf를 auto-configuration으로 띄운다. 앱 relay가 PostgreSQL outbox 행을 Kafka로 발행하고, 소비자가 inbox 예약과 업무 쓰기를 한 JPA 트랜잭션에서 한다.- offset을 0으로 되감고 다시 띄워 같은 레코드를 다시 읽혀도 handler 호출 1회, 업무 행 1개, inbox 행 1개.
- handler가 업무 쓰기 뒤 예외를 던지면 예약과 쓰기가 함께 롤백되고, platform 재시도에서 다시 처리돼 handler 호출 2회, 업무 행 1개, inbox 행 1개.
- handler는 4단계 모양(
@SystemCaller+ 직접 만든@SystemInvokeduse case)이고,composition:service-runtime이 classpath에 있어 서비스와 같은 권한 가드 아래에서 기동한다. - 소비 leaf가 기동하면 inbox 마이그레이션만
flyway_messaging_inbox_history에 적용되고 platform outbox 표는 생기지 않는다. - 테스트는 payload 타입을 등록하지 않고 inbox 표도 만들지 않는다 — 서비스가 받는 그대로다.
- 변이 확인(2026-11-03):
IdempotentConsumer의 중복 예약 검사를 지우면 offset 되감기 테스트가 handler 호출 2회·업무 행 2개로 실패한다. - 이미지는
config/testing/container-images.properties(kafka,postgres-16).
남은 것
- 템플릿 relay가 보낸 메시지의 payload는 canonical envelope JSON 전체다. 소비자 record는 envelope 모양이다.
- inbox cleanup 스케줄(
InboxCleanupJob을 어느 replica에서 언제 돌릴지)은 이 leaf가 하지 않는다.