Files
messaging-library/docs/messaging/outbox-inbox.md
T
DongHyeonka a596504e2b fix!: 2차 재리뷰가 찾은 결함 29건을 고친다
문제: 재리뷰 수정 커밋(a32b67a2)만 다시 본 2차 재리뷰가 Important 7건,
Minor 22건을 찾았다. 결과 불명 503 뒤 같은 키를 다시 보내면 Redis
store가 lease 지난 실행을 넘겨받아 작업을 다시 돌렸다. replay TTL이
lease보다 짧으면 lease 도중 key가 사라져 같은 키가 두 번 실행됐다.
@SystemInvoked 규칙이 매뉴얼 09장의 이벤트 소비 경로까지 막았다. V22가
outbox_event에 가장 강한 잠금을 lock_timeout 없이 걸었다. prod의
fixture- 거부가 HOSTNAME 같은 비밀 아닌 값까지 막았다. 데모 허용 목록의
test·demo 프로필로 sample이 뜨지 않았다. 기동 rule bean의 @Value 필드가
조용히 null이 됐다.

방법: 영역별 4묶음이 test-driven-development 절차로 실패 테스트를
먼저 쓰고 고쳤다. 결정은 재리뷰 README 9.1절이다.
- 두 멱등성 store가 같은 계약을 따른다. lease가 지난 실행 기록은 다시
  돌리지 않고 포기로 표시해 500 RECOVERY_REQUIRED로 답한다. 기록 수명은
  lease + replay TTL이고, replay-ttl < processing-lease면 기동이 실패한다.
- 사용자 transport만 @SystemInvoked use case에 닿지 못한다. 메시지
  handler·scheduler는 새 표시 @SystemCaller(reason)를 달고 use case를
  생성자에서 new로 만든다. 매뉴얼 경로를 테스트로 고정했다.
- 아직 어디에도 적용되지 않은 마이그레이션(V20·V22·알림 V11~V13·sample
  V8_1·grpc V002·V003)에 lock_timeout 5s를 넣고, 텍스트 검사기와 실 PG
  lane을 더했다. 이미 배포된 24개는 동결 목록으로 둔다.
- fixture- 검사는 비밀로 분류된 값만 본다. sample은 local·test·demo에서
  object storage를 끈다. 기동 rule bean에 주입 멤버가 있으면 모든
  프로필에서 기동이 실패한다. 리뷰어가 제안한 "static @Bean 선언 강제"는
  문제없는 등록을 막고 @Value 필드는 통과시켜서 버렸다.
- 이 수정 전에 move된 파일의 쿼터 차이를 찾는 쿼리와 재계산 SQL을
  docs/fileserver/operations.md에 적었다.

위험·한계: lease 뒤 늦게 끝난 첫 시도의 결과는 기록되지 않는다(그 요청도
500). @SystemCaller가 없는 메시지 handler, 주입 멤버가 있는 기동 rule,
working-directory 없이 ./gradlew를 부르는 workflow 명령은 파생 서비스에서
새로 실패하거나 세지지 않는다(업그레이드 안내 B-14~16·B-36·B-39).
spotbugsTestFixtures는 게이트 밖이고 기준 커밋에서도 실패하며, 새 검사기의
정규식 경고 8건이 더해졌다. 실제 CI runner 실행은 확인하지 못했다(Gitea
repo의 Actions가 꺼져 있다).

검증: ci, 두 빌드의 verifyStrictLaneStages --dry-run, mainCheck,
:integrationCheck, -p optional-platforms ci integrationCheck
performanceCheck, :performanceCheck, :releaseCheck(-PgitRevision),
verify-compose-profile-contracts(18 lane) 첫 실행 통과. 쿼터 재계산
SQL은 실 PostgreSQL 16에서 차이 2행 → 0행을 확인했다.

Refs: docs/reviews/2026-11-03-rereview/README.md 9·9.1·10절
BREAKING CHANGE: replay-ttl < processing-lease 설정은 기동 실패, ledger
release가 claim token을 받는다, HttpBodyReadException(IOException 하위)이
본문 실패를 싣는다, 기동 rule·비밀 목록 bean의 주입 멤버 금지,
verifyStrictLaneStages가 workflow 명령의 working-directory로 빌드를 정한다.
2026-11-04 01:47:50 +09:00

11 KiB

Outbox · Inbox

이 문서의 Outbox는 vendored messaging platform의 outbox다(messaging_outbox 표, messaging-reliability의 OutboxRelay). 이 템플릿 application이 쓰는 outbox는 그것이 아니다. application은 outbox_event 표(adapter:outbound:persistence-jpa)에 append하고, relay는 composition:outbox-relay가 돌린다. 그 동작과 운영은 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).

두 모델은 같은 이름의 상태가 반대 뜻이다. 이름으로 옮기면 확정 거부는 영원히 재시도되고 응답 없는 메시지는 버려진다. 대응은 아래 표 하나로만 읽는다(OutboxPublishOutcome Javadoc과 같은 내용).

일어난 일 application outbox_event platform messaging_outbox
broker가 확인했다 PUBLISHED PUBLISHED
응답이 없었다(저장됐을 수 있음) 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_TRANSACTIONAL destination의 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, 증가한 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)가 확인한다. 애플리케이션 경로(앱 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이기 때문이다.