옮겨 온 문서는 템플릿 안의 family를 전제로 쓰였다. 루트 지침은
하네스 뼈대의 빈 양식이고, 모듈 지침·제품 문서는 템플릿 경로
(src/platforms/messaging, src/config/…, cd src)와 템플릿 소비자
(app-bootstrap, adapter:*, composition:*)를 이 repo 안의 것처럼 부른다.
- AGENTS.md(38줄)·CLAUDE.md: 꼭 지킬 것 일곱(api 모듈 순수성, 템플릿
타입·경로 금지, 배포 버전·적용된 migration 불변, 인증 manifest 손으로
고치지 않기 등), 지도, 맡은 일, 검증 진입점.
- README.md: 받는 법(exclusiveContent dev.cakit), migration 위치, 지원 표
(Boot 4.0.9, kafka-clients 4.1.2, apache/kafka:4.1.0, PostgreSQL 16,
Java 21), 구조, 문서 지도, 서명 공개 키(지문 …A1C936D7F791F8AB,
grpc-library와 같은 키), 이력(템플릿 2959eff0에서 filter-repo).
- CHANGELOG.md: 1.0.0 절과 템플릿 안 코드에서 옮기는 법(패키지,
Kafka 설정 키, Gradle 좌표, 바뀌지 않는 것).
- docs/README.md, docs/work/{README,gates,release}.md,
docs/problem-statement.md: grpc-library와 같은 모양으로, 메시징의
인증 증거 게이트·migration 규칙·템플릿과 같이 고치는 경로를 넣었다.
docs/vision.md는 소유자가 쓸 자리라 비워 둔다.
- messaging/AGENTS.md, docs/messaging/*, starter README: registry 경로를
이 repo 기준으로, 템플릿 쪽 경로·타입은 「백엔드 템플릿의」로 밝혔다.
시험이 읽는 문장(지원 표의 broker·버전, 설정 참조의 YAML)은 바꾸지
않았다.
검증: scripts/verify.sh docs rc=0(vision.md 자리 알림만). desktop
mainCheck는 이 커밋 직전 트리에서 rc=0이었다. 문서가 시험에 읽히는
부분은 다음 desktop 실행으로 다시 본다.
Refs: design-docs repo-structure/05-library-repos.md 14.2절
11 KiB
Outbox · Inbox
이 문서의 Outbox는 이 라이브러리의 outbox다(
messaging_outbox표,messaging-reliability의OutboxRelay). 백엔드 템플릿 application이 쓰는 outbox는 그것이 아니다. 템플릿 application은outbox_event표(adapter:outbound:persistence-jpa)에 append하고, relay는composition:outbox-relay가 돌린다. 그 동작과 운영은 템플릿 repo의docs/manual/09-outbox-events.md,src/composition/outbox-relay/README.md,docs/runbooks/outbox-dead-letter.md,docs/runbooks/outbox-publish-failed.md에 있다. platform outbox는 소유자 결정으로 제품 안에 남아 있지만, platform outbox repository bean이 없으면 그 relay는 만들어지지 않는다(리뷰 2026-11-01 06-11).두 모델은 같은 이름의 상태가 반대 뜻이다. 이름으로 옮기면 확정 거부는 영원히 재시도되고 응답 없는 메시지는 버려진다. 대응은 아래 표 하나로만 읽는다(
OutboxPublishOutcomeJavadoc과 같은 내용).
일어난 일 application outbox_eventplatform messaging_outboxbroker가 확인했다 PUBLISHEDPUBLISHED응답이 없었다(저장됐을 수 있음) FAILED(재시도, 예산 안 씀, 끝 없음)AMBIGUOUS(재시도, 예산을 다 쓰면EXHAUSTED)지금만 거부됐다(종료·포화·credential) FAILED(재시도, 예산 안 씀, 끝 없음)FAILED(종단)확정 거부됐다(같은 payload는 또 거부) DEAD(종단, 수동 처분)FAILED(종단)publisher가 예외를 던졌고 시도 예산을 다 썼다 DEAD(종단, 수동 처분)EXHAUSTED(종단)운영자가 재시도를 멈췄다 PARKED(수동 재개·skip)없음 백엔드 템플릿 application의 소비 경로: application의
MessageHandler와 inbox 부품(애플리케이션 DataSource 위JdbcInboxRepository,PlatformTransactionManager위TransactionRunner)은 템플릿의adapter:inbound:messaging(템플릿src/adapter/inbound/messaging/README.md)이 둔다. platform starter는 두 bean이 있을 때IdempotentConsumer를 만들어INBOX_TRANSACTIONALdestination의 handler를 감싼다. 그 leaf는 inbox 마이그레이션(V1101)만 자기 history 표로 적용하므로, 아래 "location 추가"는 platform outbox를 쓰는 배포의 이야기다. payload decode 목록은 handler bean의 선언으로 만든다.
두 패턴이 각각 무엇을 해결하는가
| 패턴 | 해결하는 문제 | 해결하지 않는 문제 |
|---|---|---|
| Transactional Outbox | DB commit과 publish 사이의 창(窓) | 중복 |
| Inbox | 중복 delivery의 side effect | 유실 |
둘 다 필요하다. Outbox만으로는 exactly-once가 되지 않는다.
채택할 때 먼저 적용할 DB migration
Outbox/Inbox JDBC 모듈의 DDL은 classpath:db/migration/messaging에 있다. Messaging은
Flyway version 1000..1999를 예약해서 애플리케이션의 일반적인 저번호 migration과 버전이
겹치지 않게 한다.
배포에서 이 JDBC 구현을 채택할 때는 기존 Flyway location에 다음 location을 추가한다.
classpath:db/migration/messaging
현재 순서는 V1001..V1005(outbox/admin)와 V1101(inbox)이고, 모두
messaging-reliability-jdbc-postgresql에 있다. starter 테스트가 그 모듈을 실제 combined classpath로 올려 version 중복과 예약 대역 이탈을 검사한다. 개별 DDL의
의미와 전환 순서는 migration-guide.md를 따른다.
Outbox
business transaction과 같은 transaction에서 row를 쓴다. 둘 다 commit되거나 둘 다 안 된다.
BEGIN;
UPDATE orders SET status = 'PLACED' WHERE id = ?;
INSERT INTO messaging_outbox (message_id, destination, ...) VALUES (?, ?, ...);
COMMIT;
relay
claimBatch(owner, 100, 30s, now, maxAttempts) -- owner + fencing token으로 다중 relay 인스턴스 안전
→ publish (messageId 그대로)
→ CONFIRMED → markPublished
→ AMBIGUOUS → markAmbiguous (같은 messageId로 재시도 가능)
→ REJECTED → markFailed
row 하나의 실패는 그 row에서 끝난다. envelope로 만들 수 없는 row(예약 header msg.*를 담은 row
등)는 FAILED가 되고, publisher가 예외를 던지면 결과를 모르므로 AMBIGUOUS가 된다. 같은 batch의
나머지 row는 그대로 publish된다. pass 전체가 실패하면(DB 연결 등) WARN 로그를 남기고
messaging.outbox.relay.failed.passes 카운터를 올린다.
핵심 규칙: ambiguous는 같은 messageId로 재시도
새 id를 발급하면 "전달됐을 수도 있는 메시지"가 "확실히 두 번째인 메시지"가 되어 downstream의 어떤 중복 제거도 복구할 수 없다. failed로 표시하면 broker가 이미 가지고 있을 수 있는 메시지를 잃는다.
message_id를 primary key로 둔 것도 같은 이유다. 어떤 코드 경로도 실수로 새 id를 붙일 수 없다.
lease
status IN ('PENDING','AMBIGUOUS','IN_FLIGHT')
AND (lease_expires_at IS NULL OR lease_expires_at <= now)
AND next_attempt_at <= now
AND attempts < maxAttempts
AND (ordering_key IS NULL
OR 같은 destination·ordering_key의 더 오래된 미완료 row가 없음)
ordering_key가 있는 row는 같은 key의 더 오래된 row가 PENDING·AMBIGUOUS·IN_FLIGHT인 동안
claim되지 않는다. 이 조건이 없으면 두 relay가 같은 key의 두 row를 나눠 가져가거나, AMBIGUOUS로
재시도되는 row보다 뒤의 row가 먼저 나간다(OutboxPostgresIT#aNewerRowWaitsWhileAnOlderRowWithTheSameOrderingKeyIsUnfinished).
V1005의 partial index가 이 확인을 받친다. 더 오래된 row가 FAILED·EXHAUSTED가 되면 뒤의 row는
진행한다.
IN_FLIGHT가 목록에 있는 것이 핵심이다. relay가 publish 도중 죽으면 row는 IN_FLIGHT로 남는데,
이를 제외하면 그 메시지는 영원히 발행되지 않는다 — outbox가 막으려던 바로 그 실패다. 대신
lease가 만료됐을 때만 회수하므로, 살아 있는 relay가 들고 있는 row는 회수되지 않는다.
회수는 같은 message_id로 이루어지고 lease_token이 1 증가한다. 새 id를 발급하면 "전달됐을
수도 있는 메시지"가 "확실히 두 번째"가 되기 때문이다 (위의 AMBIGUOUS 논의와 같은 이유).
이 문단의 근거는 실제 PostgreSQL 컨테이너 레인이다:
OutboxPostgresIT#anExpiredLeaseBecomesClaimableAgain— 만료된 lease의 재회수OutboxPostgresIT#anExpiryReclaimKeepsTheMessageIdAndAdvancesTheToken— 같은 id, 증가한 tokenOutboxPostgresIT#aLeasedRowIsInvisibleToASecondRelayInstance— 살아 있는 lease는 회수 불가OutboxPostgresIT#aSupersededRelayCannotOverwriteTheOutcomeOfTheOneThatReplacedIt— fencing
partial index ix_messaging_outbox_claimable이 이 쿼리를 backlog 크기에 비례하게 유지한다.
PUBLISHED row는 retention job이 지울 때까지 쌓이기 때문이다.
Inbox
reservation과 side effect가 같은 transaction이어야 한다.
transactions.inTransaction(() -> {
if (!inbox.reserve(messageId, consumerId, now)) {
return InboxOutcome.duplicate(); // 이미 처리됨
}
return InboxOutcome.processed(sideEffect.get());
});
별도 transaction으로 예약하면 Inbox가 닫으려던 바로 그 창이 다시 열린다.
소비와 연결 (소유자 결정 10)
consume 계약은 MessageHandler<T> 하나다. handler를 bean으로 등록하면 messaging-spring-boot-starter-kafka가
그 handler가 가리키는 destination마다 Kafka consumer를 연다(app.messaging.enabled=false면 없다).
- destination profile이
guarantees.external-side-effect: INBOX_TRANSACTIONAL이면 platform이 handler를InboxMessageHandler로 감싼다. 예약과 handler의 쓰기가 같은 transaction에서 commit되고, 이미 예약된 message는 handler를 부르지 않고Success로 settle한다. 이 경우 애플리케이션이IdempotentConsumerbean(inbox repository + transaction runner)을 둬야 하며, 없으면 기동이 실패한다. - inbox의 consumer 식별자와 Kafka
group.id는 destination의consumer.group이다. 없으면 기동이 실패한다. - offset은 handler가
Success로 답하고 (inbox destination이면) 그 transaction이 commit된 뒤에만, 또는 DLQ 토픽 기록이 확인된 뒤에만 넘어간다. auto-commit은 쓰지 않는다. Retry·예외·timeout은retry.max-attempts까지 partition을 멈추고 다시 읽으며, 다 쓰면 DLQ 토픽에 원본 record를 남기고 넘어간다. DLQ가 없는 destination(at-most-once)은 넘어가지 않고 멈춘다.Reject는 at-most-once destination에서만 버리고, 그 밖에서는 dead letter로 보낸다.
실제 왕복·중복 제거·DLQ는 MessagingKafkaConsumeQualificationTest(Kafka + PostgreSQL Testcontainers)가 확인한다.
템플릿 애플리케이션 경로(앱 outbox relay가 발행 → adapter:inbound:messaging이 조립한 inbox와 JPA 트랜잭션 →
handler)의 중복 전달·실패 재처리는 템플릿의 InboxRedeliveryIntegrationTest(lane
messagingInboxRedeliveryIntegrationTest)가 확인한다. 애플리케이션 handler가 쓰기 use case를 부르는 방법
(@SystemCaller handler가 @SystemInvoked use case를 직접 만든다)은 템플릿 docs/manual/09-outbox-events.md
「소비」 4단계다.
복합 키
PRIMARY KEY (message_id, consumer_id).
message_id만으로 중복 제거하면 같은 event를 소비하는 두 번째 consumer가 첫 번째에 의해 억제된다. 각 consumer가 한 번씩 처리해야 한다.
retention
broker의 최대 redelivery window보다 길어야 한다. row를 먼저 지우면 늦게 도착한 redelivery가 두 번 처리된다.
outbox·inbox cleanup job은 한 번에 최대 1,000행씩 지우고, 지운 수가 1,000보다 적으면 멈춘다. repository port에는 개수 제한 없는 삭제 메서드가 없다.
CDC 대안
relay는 polling 하나뿐이다. Debezium Event Router 매핑(DebeziumOutboxEventRouter 등)은 조립하는
곳이 없어 2026-09-25에 삭제했다(템플릿 docs/capability-status.md 제거 표). messaging_outbox의
routing_key 컬럼은 남아 있으므로 CDC를 다시 들일 때 그 컬럼을 message key로 쓴다.
Claim Check
1 MiB 초과 payload는 broker 프레임을 키우지 않고 외부 저장소로 offload한다.
ClaimCheckReference는 digest를 필수로 가진다. claim check는 메시지를 서로 다른 retention과
replication을 가진 두 시스템으로 쪼개므로, consumer는 producer가 저장한 바로 그 bytes를 받았음을
증명할 수 있어야 한다. 그렇지 않으면 잘린 객체와 정상 객체를 구분할 수 없다.
ClaimCheckIntegrityGuard는 fetch 전에 만료를, fetch 후에 크기와 digest를 검사한다.
digest 불일치는 DESERIALIZATION이 아니라 validation 실패로 분류한다.
bytes가 깨진 JSON인 게 아니라, 틀린 bytes이기 때문이다.