Files
clean-architecture-backend-…/docs/design/2026-09-18-messaging-platform-bridge-design.md
T
DongHyeonka 7dc5725fe7 docs!: 메시징 문서를 messaging-library로 보내고 관련 저장소 절을 채운다
앞 커밋이 메시징 플랫폼을 지웠지만 살아 있는 문서는 아직 src/platforms
경로와 docs/messaging/을 부른다. 기록 8개의 머리 블록 「현재 정본」도
지운 docs/messaging/support-matrix.md를 가리킨다.

- docs/messaging/(10개)을 지운다. 같은 이름의 파일이 이력째
  messaging-library에 있다. 이 repo에서 그 내용을 부르던 문서(manual 09,
  messaging-kafka README·AGENTS)는 그 repo 파일로 링크한다.
- 기록(설계서 3, 계획서 3, 납품 패키지 2): 본문은 두고 머리 블록만
  고쳤다. 플랫폼을 다룬 것은 「없음 — messaging-library로 옮겼다」, 앱
  쪽 발행·소비를 다룬 것은 docs/manual/09-outbox-events.md.
- docs/work/reference/related-repos.md: 관련 저장소 표(메시징 줄 채움),
  라이브러리를 고치는 법, 템플릿에서 버전 올리는 법, 같이 고칠 때
  composite build(Gradle 루트가 src/라 ../../messaging-library), registry
  라이브러리 칸. 설계 14절이 근거다.
- src/config/architecture/README.md: library_groups·allowed_libraries 설명.
- docs/upgrade/2026-11-maturity-review.md 3.9절: B-57(지운 것), B-58(받는
  법·패키지·auto-config 이름), B-59(registry 칸).
- 진입 문서와 지역 지침(AGENTS.md, README.md, delegate, decisions,
  review-criteria, defect-patterns, gates, capability-status, manual 07,
  build-logic·persistence-jpa·inbound messaging·shared-contract 지침,
  env-keys 주석)에서 「들여온 제품」·src/platforms 문장을 별도 repo
  라이브러리 문장으로 바꿨다.

위험: 다른 repo 파일을 가리키는 링크는 lychee가 외부 URL로 본다(공개
repo라 익명으로 읽힌다).

검증: python3 scripts/check-docs.py OK, check-work-docs.py OK(상대 링크
깨짐 0), check-repo-layout.py OK, python3 -m unittest discover -s
scripts/tests OK.

BREAKING CHANGE: docs/messaging/이 없어졌다. 메시징 문서는
messaging-library repo의 docs/messaging/에 있다.

Refs: design-docs repo-structure/05-library-repos.md 4.3·14절
2026-11-08 17:11:33 +09:00

5.3 KiB

기록 · 설계서 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.

  • 상태: 확인 안 함
  • 작성일: 2026-09-18
  • 요약: 애플리케이션 전용 브로커 이음매를 메시징 플랫폼으로 가는 bridge 하나로 바꾸는 설계다.
  • 현재 정본: docs/manual/09-outbox-events.md

Messaging Platform Bridge Design

Goal

Replace the application-specific broker seam with one canonical anti-corruption bridge:

application-core IntegrationEventPublishPort
  -> adapter/outbound/messaging/platformbridge
  -> messaging-schema-api EncodedMessagePublisher
  -> messaging-runtime-core DefaultMessagePublisher
  -> messaging transport/runtime

The bridge must preserve canonical event identity and exact encoded bytes while reusing the platform's destination resolution, authorization, admission, runtime leasing, transport normalization, and observation pipeline.

Scope

This phase introduces and verifies the canonical bridge. It does not migrate the legacy outbox storage/relay rows, because OutboxEvent does not retain the schema/order/tenant metadata required to reconstruct ValidatedIntegrationEvent without invention.

Application boundary

Create IntegrationEventPublishPort in application-core.

Signature:

CompletionStage<OutboxPublishOutcome> publish(ValidatedIntegrationEvent event);

The application package depends only on its own canonical event model and application outcome vocabulary.

Adapter bridge

PlatformIntegrationEventPublishAdapter lives under:

adapter/outbound/messaging/platformbridge

It depends on EncodedMessagePublisher, never on a concrete broker client, runtime-core implementation, or transport SPI.

Mapping rules:

  • logicalDestinationId -> platform DestinationName.
  • contractId -> platform MessageType.
  • payloadVersion -> SchemaVersion.
  • event and causation identities must parse as UUIDv7; values are preserved exactly. Incompatible identities fail closed before the platform publisher is called.
  • occurredAt is used for both producedAt and occurredAt until the application canonical model carries a separate production timestamp. The bridge never invents a new timestamp.
  • producer is an explicit constructor/configuration value.
  • correlation, partition key, tenant, aggregate order and exact envelope bytes are preserved.
  • trace context is explicitly absent (TraceContext.none()) until the application model owns canonical trace context.
  • exact envelopeBytes become EncodedMessage bytes; no re-encoding occurs.
  • schema/catalog/binding/envelope evidence that has no first-class platform field is preserved as bounded x-ca-* headers.
  • the schema reference subject is the canonical contract id and version is the canonical payload version.

Outcome mapping

Mapping is based on completion and transmission evidence, not enum name similarity:

  • CONFIRMED -> OutboxPublishOutcome.CONFIRMED.
  • AMBIGUOUS -> OutboxPublishOutcome.AMBIGUOUS.
  • REJECTED + NOT_TRANSMITTED -> REJECTED_BEFORE_SEND.
  • REJECTED + any evidence that bytes may have left the process -> REJECTED_AFTER_BROKER.

Bridge preparation failures are definite pre-send rejection.

Platform boundary

EncodedMessagePublisher is owned by messaging-schema-api, because EncodedMessage is owned there and the dependency direction remains acyclic.

DefaultMessagePublisher implements both MessagePublisher and EncodedMessagePublisher. The encoded path skips only codec lookup/encoding; destination resolution, access policy, admission, runtime lease, transport send, deadline handling, result normalization and observation are shared with the normal publish path.

The starter exposes one DefaultMessagePublisher singleton, which therefore satisfies both public interfaces.

Spring ownership

MessagingBridgeRootAutoConfiguration owns the bridge bean when an EncodedMessagePublisher is present and app.messaging.producer-id is explicitly configured. Producer identity is never inferred from spring.application.name or invented. Application bootstrap must not construct Kafka producer clients or implement broker-specific send behavior.

The existing KafkaSender / KafkaMessageBroker path remains temporarily for the legacy OutboxEvent and realtime publishers, which do not yet carry enough canonical metadata to enter the new bridge without invention. It is explicitly transitional and is removed only with the legacy outbox/realtime cutover. The new canonical bridge never calls it.

Verification

Required checks:

  1. DefaultMessagePublisherTest: pre-encoded publish preserves bytes and skips codec while still exercising central pipeline.
  2. PlatformIntegrationEventPublishAdapterTest: golden mapping, outcome mapping, fail-closed identity behavior.
  3. outbound messaging module tests/check.
  4. messaging runtime/starter tests.
  5. app-bootstrap system test and architecture test after adding the canonical bridge while retaining the documented legacy seam.
  6. search proving app-bootstrap has no direct native Kafka sender configuration.
  7. dependency/build lock refresh only where dependency ownership changed.
  8. git diff --check.