Files
clean-architecture-backend-…/docs/messaging/outbox-inbox.md
T
DongHyeonkaandClaude Opus 5.5 6d27356e2b refactor: 부가 기능을 capability 모듈로 포장하고 기본 조립을 web-only로 전환
설계: docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md
계획/진행 기록: docs/superpowers/plans/2026-09-25-capability-module-packaging.md

- Wave 0: 규칙 고정(AGENTS.md capability 완료 기준·테스트 규칙) + 차단 결함 7건
  (compose overlay 검사, redis-sdk CI job, 적용된 V9/V13 원복 + V16, @EnableScheduling,
  messaging bridge 순서, prod 에러 상세 validator, sample loggers read-only)
- Wave 1: 데이터·보안 Critical 10건 (durable operation 25P02, operation 유스케이스 이동,
  outbox 재인코딩, Kafka TLS/SASL, 알림 트랜잭션, SNS 서명, tus checksum, GraphQL fragment,
  Redis lane, gRPC FAILED_TERMINAL)
- Wave 2: 리팩터링 잔재·실험용 자리 삭제, outbox v1 fencing(V17), 멱등성 V2 정본화
- Wave 3: 라이브러리형 코드 정리(동작하지 않는 설정·인터페이스·gate 제거, web-advanced 분리)
- Wave 4: capability 11개를 "있으면 켜짐" 모듈로 포장, 끄는 장치 제거, 기본 조립 web-only,
  qualificationBootJar 분리
- Wave 5: 빌드 로직 축소(17.2k -> 10.8k줄), sample 테스트 컨벤션 적용

삭제한 코드는 docs/capability-status.md "제거된 코드" 표에 복구 커밋(208077fd)과 함께 기록.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-25 12:49:07 +09:00

5.3 KiB

Outbox · Inbox

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

패턴 해결하는 문제 해결하지 않는 문제
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..V1004(outbox/admin)와 V1101(inbox)이다. starter 테스트가 두 JDBC 모듈을 실제 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

leaseBatch(100, 30s)   -- lease로 다중 relay 인스턴스 안전
→ publish (messageId 그대로)
→ CONFIRMED  → markPublished
→ AMBIGUOUS  → markAmbiguous  (같은 messageId로 재시도 가능)
→ REJECTED   → markFailed

핵심 규칙: 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

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가 닫으려던 바로 그 창이 다시 열린다.

복합 키

PRIMARY KEY (message_id, consumer_id).

message_id만으로 중복 제거하면 같은 event를 소비하는 두 번째 consumer가 첫 번째에 의해 억제된다. 각 consumer가 한 번씩 처리해야 한다.

retention

broker의 최대 redelivery window보다 길어야 한다. row를 먼저 지우면 늦게 도착한 redelivery가 두 번 처리된다.

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