앞 커밋이 메시징 플랫폼을 지웠지만 살아 있는 문서는 아직 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절
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-> platformDestinationName.contractId-> platformMessageType.payloadVersion->SchemaVersion.- event and causation identities must parse as UUIDv7; values are preserved exactly. Incompatible identities fail closed before the platform publisher is called.
occurredAtis used for bothproducedAtandoccurredAtuntil 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
envelopeBytesbecomeEncodedMessagebytes; 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:
DefaultMessagePublisherTest: pre-encoded publish preserves bytes and skips codec while still exercising central pipeline.PlatformIntegrationEventPublishAdapterTest: golden mapping, outcome mapping, fail-closed identity behavior.- outbound messaging module tests/check.
- messaging runtime/starter tests.
- app-bootstrap system test and architecture test after adding the canonical bridge while retaining the documented legacy seam.
- search proving app-bootstrap has no direct native Kafka sender configuration.
- dependency/build lock refresh only where dependency ownership changed.
git diff --check.