Files
clean-architecture-backend-…/src/adapter/outbound/messaging/README.md
T
DongHyeonka 08f932123a docs(agents)!: leaf 지역 규칙 문서를 같은 폴더 AGENTS.md로 옮긴다
leaf·family 지역 규칙은 지금 src/**/CLAUDE.md에만 있어서 Claude Code
밖의 에이전트는 이 규칙을 정본 이름으로 찾지 못한다. 소유자가
2026-11-07에 루트와 하위 폴더 모두 AGENTS.md를 정본으로 정했다
(design-docs harness/01-harness-design.md 13절 Q1·Q2).

- 28개 파일을 git mv로 같은 폴더 AGENTS.md로 옮기고, 그 자리
  CLAUDE.md에는 `@AGENTS.md` 한 줄만 둔다. 이 세션에서
  src/domain-core 파일을 열자 CLAUDE.md의 가져오기가 펼쳐져
  AGENTS.md 본문이 함께 읽히는 것을 확인했다. 그래서 Claude Code는
  지금처럼 그 폴더를 만질 때 규칙을 읽는다.
- 버린 대안: 심볼릭 링크(Edit 도구가 링크를 통해 쓰지 않는다),
  CLAUDE.md 그대로 두기(다른 에이전트가 못 찾는다).
- 살아 있는 문서와 테스트 코드의 leaf 규칙 경로를 새 이름으로 바꿨다.
  기록 문서(evidence, upgrade, design, history, reviews, adr)는 쓴
  때의 경로를 그대로 둔다.
- link-check workflow(lychee)는 src/**/CLAUDE.md만 본다. 내용이
  AGENTS.md로 가면 상대 링크가 검사 밖으로 나가므로, PR마다 도는
  check-docs.py에 살아 있는 문서 전체의 상대 링크 검사를 더했다.
  workflow는 CI 재편 몫이라 고치지 않았다.
- check-work-docs.py의 이력 ID 검사도 src/**/AGENTS.md를 본다.

위험: git은 이 커밋을 "CLAUDE.md 수정 + AGENTS.md 추가"로 본다(같은
이름의 새 파일이 생겨 이름 바꾸기로 잡히지 않는다). 옛 이력은
`git log -- <폴더>/CLAUDE.md`로 본다. 코드 주석의 "CLAUDE.md"는
가져오기를 거쳐 같은 문서에 닿으므로 운영 코드는 고치지 않았다.

검증: python3 scripts/check-docs.py, python3 scripts/check-work-docs.py,
python3 -m unittest discover -s scripts/tests 모두 rc=0. 링크 검사
시험은 검사 조건을 끈 사본에서 7건 중 3건이 실패했다.

BREAKING CHANGE: 파생 서비스의 leaf 규칙 문서 이름이 AGENTS.md로
바뀐다. 동기화 뒤 각 leaf의 CLAUDE.md는 `@AGENTS.md` 한 줄이다.
2026-11-07 21:58:12 +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과 이 모듈의 AGENTS.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).

정해진 플랫폼 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의 qualification lane 둘을 묶은 task다. 이 leaf는 그 검증에 관여하지 않는다.

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