Files
messaging-library/docs/messaging/outbox-inbox.md
T
DongHyeonka 899f1f920c feat!: 남은 리뷰 발견을 고치고 개발 매뉴얼과 기능 생성 명령을 더한다
문제: High·P1을 고친 뒤에도 P2·P3 약 90건이 남았다. 연결·구독·메시지
크기 상한이 없는 전송(WebSocket·gRPC·GraphQL deadline), 낙관적 충돌의
500, upsert 경쟁, Mongo 무제한 timeout, 샘플 목록 N+1, 갈라진 복사본
(TenantId 3벌, 이벤트 ID 문법 5곳, SQLState 표 2벌), 문서를 읽는 PR
테스트와 캐시를 막는 lane 설정 등이다. 새 기능을 어디에 어떤 순서로
만드는지 알려 주는 문서와 도구가 없었다. MinIO 공식 이미지가 사라져
객체 저장소 lane이 돌지 않았다.

방법: 영역별 묶음으로 실패 테스트를 먼저 쓰고 고쳤다. 고치는 중에 찾은
결함도 함께 고쳤다(durable operation id가 UUIDv4라 이벤트가 전부 DEAD,
S3 어댑터 생성·작은 chunk 읽기 실패, Redis 조건부 기록의 EVALSHA 권한).
MinIO는 pgsty/minio를 digest로 고정했다(Chainguard는 태그·실행 사용자·
mc 이미지 문제로 버림). docs/manual/에 작업 순서와 판단 지점을 쓰고,
scripts/new-feature.sh가 5개 leaf에 뼈대를 만든다. 생성→빌드→통과
왕복을 verifyFeatureScaffold가 mainCheck에서 본다. 묶음별 결과와
결정은 리뷰 README 14절에 있다.

위험·한계: 파생 서비스 동작이 바뀐다. JDBC batch 50 기본, 운영 jar에서
H2 제거, 트랜잭션 30초 제한, 격리 수준을 Hikari에서 고정, gRPC·
WebSocket·GraphQL 새 한도, correlation ID 규칙 밖이면 서버가 교체,
샘플 키 오류 코드 IDEMPOTENCY_KEY_INVALID. 새 leaf 두 개
(composition:durable-operation, adapter:inbound:messaging)와 새
마이그레이션(postgresql V20·V21, notification V11·V12, sample V8_1,
grpc-ledger V002)이 생긴다. V21 유일 인덱스는 기존 중복이 있으면
실패한다(runbook에 확인 쿼리).

검증: ci, mainCheck(생성 명령 왕복 포함), integrationCheck(MinIO 포함
전 컨테이너 lane), -p optional-platforms ci integrationCheck 통과.

Refs: docs/reviews/2026-11-01-maturity-review/README.md 14절
BREAKING CHANGE: JDBC batch 기본 켜짐, H2 운영 의존 제거, 트랜잭션
기본 제한 30초, gRPC·WebSocket·GraphQL 서버 한도 기본값 추가,
샘플 Idempotency-Key 오류 코드 변경.
2026-11-03 19:52:06 +09:00

8.5 KiB

Outbox · Inbox

이 템플릿 application의 소비 경로: application의 MessageHandler와 inbox 부품(애플리케이션 DataSource 위 JdbcInboxRepository, PlatformTransactionManager 위 TransactionRunner)은 adapter:inbound:messaging(src/adapter/inbound/messaging/README.md)이 둔다. platform starter는 두 bean이 있을 때 IdempotentConsumer를 만들어 INBOX_TRANSACTIONAL destination의 handler를 감싼다.

두 패턴이 각각 무엇을 해결하는가

패턴 해결하는 문제 해결하지 않는 문제
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, 증가한 token
  • OutboxPostgresIT#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한다. 이 경우 애플리케이션이 IdempotentConsumer bean(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)가 확인한다.

복합 키

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이기 때문이다.