Files
clean-architecture-backend-…/src/adapter/outbound/messaging/README.md
T
DongHyeonka bbe944bd3c fix!: 재리뷰가 찾은 결함과 색인에서 빠졌던 발견 5건을 고친다
문제: 성숙도 리뷰 수정을 다시 읽은 재리뷰(Critical 0, 회귀 0)가
Important 27건·Minor 41건을 찾았다. 수정이 새로 만든 결함이 많았다.
@SystemInvoked가 권한 규칙의 탈출구가 됐고, 데모 계정 거부가 정확히
prod일 때만 걸렸고, outbox 순서 번호가 업그레이드 때 뒤로 갔고,
GraphQL union 아래 복잡도가 0이었고, 서블릿 오류 응답이 success:true로
나갔고, 호출자 deadline이 breaker를 열었다. 원래 리뷰 색인이 06 영역
발견 5건(06-10~14)을 빠뜨려 그동안 처리되지 않았다.

방법: 영역별 7묶음이 test-driven-development 절차로 실패 테스트를
먼저 쓰고 고쳤다. 결정은 재리뷰 README 4절에 적었다: 순서 번호는 V21이
기록한 전역 floor부터, 데모 계정은 local·test·demo 허용 목록,
@SystemInvoked bean은 기동 실패, complete 단계 실패는
IDEMPOTENCY_COMPLETION_UNKNOWN(결과 불명), 캐시 조건부 쓰기는 별도
SCRIPT lane, strict lane 정책은 build cache 입력, 끝나지 않는 재시도
행은 원인 코드·지표·PARKED 절차. 레지스트리가 선언만 하고 아무 코드도
내보내지 않던 redis.capability.* 지표 6개는 빼고 runbook을 실제
지표(redis.lane.*) 기준으로 고쳤다.

위험·한계: V21을 V22 없이 직접 고쳤다(어느 배포에도 아직 없음). 이
브랜치의 V21을 적용한 개발 DB는 다시 만들어야 한다. 서블릿 오류
디스패치를 보안 체인이 허용한다. 발행·저장소 포트 시그니처가 바뀌어
파생 서비스 코드가 깨진다. prod에서 fixture-로 시작하는 설정값은
기동을 막는다. httpclient failure-injection lane의 main 단계 중복
실행은 이전 결정대로 남겼다. 실제 CI runner 실행은 확인하지 못했다.

검증: ci, mainCheck, :integrationCheck, -p optional-platforms ci
integrationCheck performanceCheck, :performanceCheck, :releaseCheck
(-PgitRevision), verify-compose-profile-contracts(18 lane) 통과.
첫 실행의 실패 2건(FindSecBugs 1, sample 동시 생성 테스트의 v4 event
id)은 고친 뒤 ci·integrationCheck·mainCheck를 다시 돌려 통과했다.

Refs: docs/reviews/2026-11-03-rereview/README.md 3·4·6·7절
BREAKING CHANGE: outbox 발행 포트와 저장소 포트 시그니처, 순서 번호
첫 값(V21 floor 다음), 샘플 데모 계정 프로필 허용 목록, 새 오류 코드
IDEMPOTENCY_COMPLETION_UNKNOWN, prod의 fixture- 값 거부, 기동 rule은
static·의존 없음이어야 한다.
2026-11-03 23:29:35 +09:00

7.5 KiB

adapter:outbound:messaging — 설계 결정 참조

메시징(broker publish + outbox relay 발행) 아웃바운드 어댑터 모듈. 패키지 루트: dev.caskeleton.adapter.outbound.messaging. outbox relay 실패는 이 모듈이 별도의 typed report adapter로 구조화한다.

허용/금지 의존 정책은 src/config/architecture/modules.json과 이 모듈의 CLAUDE.md가 소유한다. 이 문서는 코드 주석에서 덜어낸 설계 결정의 근거를 모아둔 참조용 기록이다.

모듈 개요

application-core의 OutboxMessagePublishPort와 canonical IntegrationEventPublishPort 뒤에 두는 선택형 연동 어댑터다. 서비스는 이 모듈을 직접 고르지 않고 runtimeOnly project(':adapter:outbound:messaging-kafka') 한 줄로 받는다(추가할 한 줄·env 키는 messaging-kafka README). 모듈이 있으면 켜지고 app.messaging.enabled=false로만 끈다.

발행 경로는 하나다.

OutboxMessagePublishPort → OutboxMessagePublishAdapter → IntegrationEventPublishPort → PlatformIntegrationEventPublishAdapter → EncodedMessagePublisher

bridge는 broker SDK나 transport SPI를 직접 보지 않는다. legacy KafkaSender/MessageBroker R0 seam과 그 위의 MessagePublisher·OutboxEnvelopeJson은 outbox를 canonical 하나로 통일하면서 삭제했다(2026-09-28, 소유자 결정 7).

canonical platform bridge

IntegrationEventPublishPort는 app.messaging.producer-id가 명시되고 platform publisher bean이 있을 때만 생성된다. exact ValidatedIntegrationEvent.envelopeBytes()를 보존하고 platform의 중앙 publish pipeline을 탄다. producer id는 host/pod/process 이름에서 추측하지 않는다.

OutboxMessagePublishAdapter는 claim된 row의 validated event를 그대로 bridge에 넘기고 platform 결과를 application 결과(CONFIRMED·AMBIGUOUS·REJECTED_BEFORE_SEND·REJECTED_AFTER_BROKER· REJECTED_RETRYABLE)로 번역해 relay에 돌려준다. 다시 직렬화하지 않는다.

platform REJECTED 중 FailureDescriptor.retryable()이 true인 것(종료 중 SHUTTING_DOWN, permit 대기 초과, PUBLISH_RUNTIME_UNAVAILABLE, KAFKA_TRANSPORT_CLOSED, Kafka 인증·인가 실패)은 REJECTED_RETRYABLE로 번역한다. relay는 이 값을 DEAD로 보내지 않고 재시도한다. 확정 거부 두 값으로 번역하면 "같은 payload는 또 거부된다"로 읽혀 커밋된 이벤트와 그 aggregate의 뒤 이벤트가 바로 멈춘다(2026-11-01 리뷰 06-01). AMBIGUOUS로 번역하지 않은 이유: 동작은 같지만 "전송됐을 수 있음"이라는 거짓 정보가 남아 중복 경고를 오염시킨다.

실패 원인 코드

결과(outcome)는 relay가 무엇을 할지만 정한다. 종료 중 거부, 닫힌 transport, 거부된 credential은 모두 REJECTED_RETRYABLE 하나다. 그런데 이 셋은 끝이 없는 재시도다(시도 예산을 쓰지 않는다). 그래서 bridge는 platform FailureDescriptor.code()를 버리지 않고 OutboxPublishAttempt.failureCode()로 함께 넘긴다 (재리뷰 2026-11-03 RR-05-03). relay는 그 코드를 행의 last_failure_code(V22)와 실패 로그의 error.reason에 남긴다. 운영자는 이 값으로 "credential이 진짜 틀렸다"와 "broker가 이 레코드만 받지 않는다"를 가른다(docs/runbooks/outbox-publish-failed.md §4.1).

  • platform code는 이미 정제된 이름이다(KAFKA_AUTHENTICATIONEXCEPTION, PUBLISH_DEADLINE_EXCEEDED 등). driver 메시지가 아니므로 그대로 옮긴다. application 코드 문법([A-Za-z0-9][A-Za-z0-9._:-]*, 120자)에 맞지 않는 code는 그 실패의 FailureCategory 이름으로 옮긴다.
  • platform으로 옮길 수 없는 event(아래 id 규칙)는 bridge가 EVENT_NOT_REPRESENTABLE로 거부한다.
  • 버린 대안: relay가 platform 타입을 직접 보는 것(경계가 깨진다), outcome 값을 원인별로 늘리는 것(relay가 할 일은 같은데 분기만 는다).

event id → message id

application EventId는 문자열이고 platform MessageId는 UUIDv7만 받는다. bridge는 event id가 정규 소문자 UUIDv7 문자열일 때만 같은 값으로 옮기고, 그 밖(대문자·축약 표기·v4 등 다른 버전)은 다른 문자열의 message id로 바꿔 보내지 않고 REJECTED_BEFORE_SEND로 거부한다(relay는 DEAD). 소비자 중복 제거 키가 event id라서 값을 바꿔 보내면 중복 제거가 깨지기 때문이다(리뷰 2026-11-01 06-06).

같은 규칙이 append 쪽에 먼저 있다. IntegrationEventDraft가 정규 소문자 UUIDv7이 아닌 event id와 causation id를 거부하므로(IntegrationIdentity.isCanonicalUuidV7), 그런 id는 업무 트랜잭션 안에서 실패한다 (재리뷰 2026-11-03 RR-05-04). bridge의 거부는 이 규칙 전에 쓰인 행(저장 문법 EventId는 그대로 넓다)을 위한 마지막 방어선이다.

outbox 발행 포트에는 대역이 없다

OutboxMessagePublishPort의 대역(항상 던지는 publisher)은 두지 않는다. 대역도 bean이므로 relay 스케줄러의 조건을 채우고, relay는 모든 PENDING 행을 그 대역에 실패시켜 DEAD로 소진한다. 그래서 모듈이 있고 켜져 있는데 IntegrationEventPublishPort가 없으면(producer id가 비었거나 platform transport가 없으면) startup을 거부한다.

중복 가능 구간

publisher 정상 반환 뒤 DB mark가 실패하면 row는 IN_FLIGHT에 남아 timeout reclaim 후 같은 event가 다시 publish될 수 있다. 같은 event id로 다시 나가므로 consumer는 event id로 중복을 걸러야 한다. 같은 aggregate의 row는 (aggregate_sequence, event_index) 순서로 하나씩 풀린다.

OutboxRelayFailureReport 구조화 ERROR

MessagingConfig는 정확히 하나의 Slf4jOutboxRelayFailureReportAdapter를 등록한다. dependency_name은 platform이 쓰는 broker 선택값(app.messaging.broker, 기본 kafka)이고, 비어 있으면 messaging-platform이다. 이 adapter는 confirmed FAILED/DEAD report 하나를 SLF4J 2 fluent ERROR 하나로 렌더링한다.

공통 field는 error.code, error.category, error.cause_type, error.reason, dependency_name, dependency_type=messaging, outcome, event_id, event_type, aggregate_id, correlation_id, attempt_count, runbook_link다. retry report만 next_attempt_at을 추가한다. error.reason은 위 실패 원인 코드다. payload/envelope/exception-derived field는 받거나 렌더링하지 않는다. logging 내부 RuntimeException은 adapter와 use case 양쪽에서 방어하므로 persisted FAILED/DEAD outcome을 바꾸지 않는다.

encoder는 이 모듈에 없다

템플릿의 IntegrationEventEncoderPort 구현(JsonIntegrationEventEncoder)은 adapter:outbound:support에 있다. use case가 append 전에 encode하므로 outbox를 쓰는 모든 조립에 있어야 하고, 이 모듈은 발행 쪽에만 있다. 옛 R1 encoder 체인(contract·destination·config· envelope·realtime)은 2026-09-25에 삭제됐고 복구 경로는 docs/capability-status.md 제거 표에 있다.

integration event 계약 검증은 루트 verifyMessagingContracts(src/build.gradle)가 한다. application-core· shared-contract·sample-portfolio의 qualification lane 셋을 묶은 task다. 이 leaf는 그 검증에 관여하지 않는다.

canonical path는 platform PublishResult의 confirmation/transmission evidence를 application OutboxPublishOutcome으로 명시적으로 변환하고, 실패 code를 OutboxPublishAttempt에 함께 싣는다.