From f412efff7353bfd523ebd81f16b9b61f91851921 Mon Sep 17 00:00:00 2001 From: donghyeon-ka Date: Fri, 18 Sep 2026 15:22:30 +0900 Subject: [PATCH] =?UTF-8?q?refactor:=20=EB=B9=8C=EB=93=9C=20=EB=A1=9C?= =?UTF-8?q?=EC=A7=81=20=EA=B0=9C=EC=84=A0,=20gradle=20=ED=8C=8C=EC=9D=BC?= =?UTF-8?q?=20=EA=B2=BD=EB=9F=89=ED=99=94?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/messaging/configuration-reference.md | 23 +++++ messaging/CLAUDE.md | 31 ++++--- messaging/messaging-kafka/build.gradle | 91 +++++-------------- .../runtime/DefaultMessagePublisher.java | 58 +++++++++--- .../runtime/DefaultMessagePublisherTest.java | 41 +++++++++ .../schema/EncodedMessagePublisher.java | 24 +++++ .../MessagingCoreAutoConfiguration.java | 2 +- .../MessagingStarterOffContractTest.java | 2 + 8 files changed, 176 insertions(+), 96 deletions(-) create mode 100644 messaging/messaging-schema-api/src/main/java/dev/caskeleton/messaging/schema/EncodedMessagePublisher.java diff --git a/docs/messaging/configuration-reference.md b/docs/messaging/configuration-reference.md index 31afe67..6fa2a81 100644 --- a/docs/messaging/configuration-reference.md +++ b/docs/messaging/configuration-reference.md @@ -13,6 +13,29 @@ > 어떤 binder도 그것을 읽지 않았다 — 문서대로 설정한 배포는 아무것도 바뀌지 않았고 아무 말도 듣지 > 못했다 (MSG-008). +## Application publish bridge identity + +Application의 canonical integration event를 platform publish pipeline으로 보낼 때는 +`app.messaging.producer-id`를 명시한다. 같은 값의 환경변수 이름은 +`APP_MESSAGING_PRODUCER_ID`다. 이 값은 host/pod 이름이 아니라 배포와 무관하게 유지되는 논리적 +producing-service identity다. + +값이 없으면 `IntegrationEventPublishPort` bridge 자체를 만들지 않는다. `spring.application.name`이나 +현재 process 이름으로 추론하지 않는다. 기존 legacy `OutboxEvent`/realtime 경로는 별도 cutover가 +끝날 때까지 `app.messaging.broker` 경로를 유지한다. + +## Outbox canonical transport-only cutover + +`APP_OUTBOX_CANONICAL_TRANSPORT_ENABLED` / `ca-skeleton.outbox.canonical-transport-enabled`은 +기존 `outbox_event` writer/claim/status authority를 유지한 채 canonical row의 **transport만** platform +publish path로 보내는 compatibility gate다. 기본값은 `false`이며 `POLLING_V2`를 활성화하지 않는다. + +`true`일 때는 `OutboxAppendPort`가 `ValidatedIntegrationEvent`의 exact envelope bytes와 canonical +metadata를 기존 outbox row에 저장하고, claim된 canonical row는 `IntegrationEventPublishPort`로 간다. +legacy row는 계속 `MessageBroker`를 사용한다. 따라서 mixed-row compatibility 기간에는 relay가 켜져 +있다면 `app.messaging.broker`도 계속 필요하며, canonical path를 위해 `IntegrationEventPublishPort`도 +추가로 필요하다. legacy backlog가 0이라는 별도 증거 없이 broker 요구를 제거하지 않는다. + ## Destination profile ```yaml diff --git a/messaging/CLAUDE.md b/messaging/CLAUDE.md index e99d76b..dacd813 100644 --- a/messaging/CLAUDE.md +++ b/messaging/CLAUDE.md @@ -54,21 +54,28 @@ experimental transport, 일부 codec/bridge/testkit처럼 starter graph에 들 새 leaf를 application에 채택할 때는 starter 또는 composition dependency와 architecture edge policy, qualification/support 상태를 함께 변경한다. -## application이 이 family에 도달하는 경로 (MSG-015, 미해결) +## application이 이 family에 도달하는 경로 (MSG-015, canonical bridge 구현 / legacy cutover 잔존) -리뷰(`docs/reviews/2026-08-14-messaging-module-code-review.md` §6.1·§6.3)가 정한 흐름은 -`application-owned port → platform anti-corruption bridge → platform`이고, §6.2는 그 bridge의 자리를 -`adapter/outbound/messaging/platformbridge/`로 지정한다. §6.3 첫 규칙: **application은 신규 -broker/runtime 타입을 직접 보지 않고 자기 port만 소유한다.** +리뷰(`docs/reviews/2026-08-14-messaging-module-code-review.md` §6.1·§6.3)가 정한 +`application-owned port → platform anti-corruption bridge → platform` 경로는 이제 존재한다. -**현재 그 bridge가 없다.** `adapter/outbound/messaging`은 platform에 의존하지 않고(registry의 -`allowed_dependencies` 참조), `app-bootstrap`이 starter를 직접 문다. 그래서 서로를 모르는 messaging -스택 두 개가 한 아티팩트에 있고, 그것이 `kafkaSeamProducer`/`messagingKafkaProducer` bean 이름 충돌로 -드러났다. +- application-owned port: `IntegrationEventPublishPort` +- bridge: `adapter/outbound/messaging/platformbridge/PlatformIntegrationEventPublishAdapter` +- platform boundary: `EncodedMessagePublisher` +- central implementation: `DefaultMessagePublisher` -이것이 리뷰의 **MSG-015 (P0)** 이며 닫히지 않았다. 지금 안전한 이유는 설계가 아니라 기본값이다 — -`app.messaging.enabled=false`. 이 스위치를 켜는 배포는 port를 거치지 않는 경로로 platform을 쓰게 된다. -bridge 구현은 런타임 배선 변경이라 리뷰가 말한 대로 별도 change set이다. +bridge는 exact canonical envelope bytes를 다시 serialize하지 않고, destination/access/admission/runtime +lease/transport/outcome normalization/observation은 platform 중앙 publish path를 그대로 탄다. bridge +package는 `messaging-core-api`와 `messaging-schema-api`만 보며 concrete runtime/transport/Kafka 타입을 +직접 보지 않는다. + +다만 **MSG-015의 전체 cutover가 끝난 것은 아니다.** legacy `OutboxEvent`와 realtime publisher는 +schema/order/tenant 등 canonical metadata가 부족해 아직 `MessageBroker → KafkaSender` R0 경로를 +사용한다. 그 metadata를 추측해 platform envelope를 만드는 것은 금지한다. 따라서 legacy outbox +storage/relay migration을 별도 change set으로 완료한 뒤에만 R0 seam을 제거한다. + +canonical bridge의 producer identity는 `app.messaging.producer-id`로 명시한다. 값이 없으면 bridge bean을 +만들지 않으며 `spring.application.name`/host/pod 이름에서 identity를 발명하지 않는다. ## Stable 승격에 필요한 증거 diff --git a/messaging/messaging-kafka/build.gradle b/messaging/messaging-kafka/build.gradle index 355925d..a14c287 100644 --- a/messaging/messaging-kafka/build.gradle +++ b/messaging/messaging-kafka/build.gradle @@ -1,5 +1,6 @@ plugins { id 'ca.jmh-benchmarks' + id 'ca.messaging-certification' } dependencies { @@ -43,30 +44,29 @@ dependencies { // the lane rewrites it. strictTestLanes { lane('messagingCertificationTest') { + integration() tag = 'messaging-certification' description = 'Runs the broker fault scenarios against a real Kafka and writes the ' + 'certification evidence the compatibility matrix reads.' - customize = { test -> - // Pinned images. A certification claim names the build it was made against, so a - // floating tag would make a red run unattributable and a green one unrepeatable. - // `-PmessagingKafkaImage=` overrides for a one-off run against another version. - test.systemProperty 'messaging.kafka.image', - (project.findProperty('messagingKafkaImage') ?: 'apache/kafka:4.1.0').toString() - test.systemProperty 'messaging.toxiproxy.image', - (project.findProperty('messagingToxiproxyImage') - ?: 'ghcr.io/shopify/toxiproxy:2.12.0').toString() - test.systemProperty 'messaging.certification.manifest', - project.layout.buildDirectory - .file('messaging-certification/broker-certification-evidence.jsonl') - .get().asFile.absolutePath - // The commit is part of the evidence: "certified" is a claim about one source tree. - // Read from the environment rather than a `-P` flag so the CI job's command line stays - // the literal grammar the gate matrix lint accepts. - test.systemProperty 'messaging.certification.commit', - (project.findProperty('certificationCommit') - ?: providers.environmentVariable('GITHUB_SHA').getOrElse('local')) - .toString() - } + // Pinned images. A certification claim names the build it was made against, so a + // floating tag would make a red run unattributable and a green one unrepeatable. + // `-PmessagingKafkaImage=` overrides for a one-off run against another version. + systemProperty 'messaging.kafka.image', + (project.findProperty('messagingKafkaImage') ?: 'apache/kafka:4.1.0').toString() + systemProperty 'messaging.toxiproxy.image', + (project.findProperty('messagingToxiproxyImage') + ?: 'ghcr.io/shopify/toxiproxy:2.12.0').toString() + systemProperty 'messaging.certification.manifest', + project.layout.buildDirectory + .file('messaging-certification/broker-certification-evidence.jsonl') + .get().asFile.absolutePath + // The commit is part of the evidence: "certified" is a claim about one source tree. + // Read from the environment rather than a `-P` flag so the CI job's command line stays + // the literal grammar the gate matrix lint accepts. + systemProperty 'messaging.certification.commit', + (project.findProperty('certificationCommit') + ?: providers.environmentVariable('GITHUB_SHA').getOrElse('local')) + .toString() } } @@ -80,52 +80,3 @@ tasks.named('test', Test) { excludeTags 'messaging-certification' } } - -tasks.register('verifyMessagingCertificationEvidence') { - group = 'verification' - description = 'Fails when the committed broker certification manifest claims a scenario the ' + - 'certification lane did not produce.' - dependsOn 'messagingCertificationTest' - - def produced = layout.buildDirectory - .file('messaging-certification/broker-certification-evidence.jsonl') - def committed = rootProject.file( - 'messaging/messaging-testkit/src/main/resources/messaging/' + - 'broker-certification-evidence.jsonl') - inputs.file(produced) - inputs.file(committed) - outputs.file(layout.buildDirectory.file('reports/messaging-certification-evidence.txt')) - // A gate whose result can be served from an earlier run is evidence about that run. - outputs.upToDateWhen { false } - - doLast { - // The commit and the observation instant differ on every run by design, so they are not - // part of the comparison — what has to match is which adapter proved which scenario against - // which image, and which test produced it. - Closure> claims = { File file -> - file.readLines('UTF-8') - .findAll { !it.trim().isEmpty() } - .collect { line -> - line.replaceAll(/,"gitCommit":"[^"]*"/, '') - .replaceAll(/,"observedAt":"[^"]*"/, '') - } - .toSet() - } - Set ran = claims(produced.get().asFile) - Set shipped = claims(committed) - - if (ran != shipped) { - def unproven = shipped - ran - def unrecorded = ran - shipped - throw new GradleException( - "the committed certification manifest does not match this run.\n" + - " claimed but not produced: ${unproven.isEmpty() ? 'none' : unproven}\n" + - " produced but not claimed: ${unrecorded.isEmpty() ? 'none' : unrecorded}\n" + - "Copy ${produced.get().asFile} over ${committed} — the manifest is a " + - "record of a run, not a statement about one.") - } - def report = outputs.files.singleFile - report.parentFile.mkdirs() - report.text = "scenarios=${ran.size()} manifest=${committed}\n" - } -} diff --git a/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisher.java b/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisher.java index 7298578..4942565 100644 --- a/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisher.java +++ b/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisher.java @@ -13,6 +13,7 @@ import dev.caskeleton.messaging.api.publish.RoutingOutcome; import dev.caskeleton.messaging.policy.DestinationProfile; import dev.caskeleton.messaging.policy.MessagingAdmissionController; import dev.caskeleton.messaging.schema.EncodedMessage; +import dev.caskeleton.messaging.schema.EncodedMessagePublisher; import dev.caskeleton.messaging.schema.MessageCodec; import dev.caskeleton.messaging.schema.MessageCodecRegistry; import dev.caskeleton.messaging.security.DestinationAccessPolicy; @@ -52,7 +53,7 @@ import java.util.function.LongSupplier; * cancellation. A permit or lease that leaks on the failure path is a limiter that shrinks by one * per failure until it stops accepting anything. */ -public final class DefaultMessagePublisher implements MessagePublisher { +public final class DefaultMessagePublisher implements MessagePublisher, EncodedMessagePublisher { private final DestinationProfileRegistry destinations; @@ -168,25 +169,53 @@ public final class DefaultMessagePublisher implements MessagePublisher { profile = destinations.require(destination.name()); requireSupportedOptions(profile, options); if (!access.mayPublish(destination.name())) { - // Before encoding: an unauthorized publish must not serialise the payload, because the - // encoded bytes are what a claim-check or a log would then be holding. return rejected( "PUBLISH_FORBIDDEN", - "this application may not publish to '" + destination.name().value() + '\'', + "this application may not publish to '" + destination.name().value() + "'", startedAt); } encoded = encode(message); } catch (RuntimeException beforeTheWire) { - // Nothing left this process, so the outcome is definite. Reporting it as ambiguous would send - // the caller into reconciliation for a message no broker ever saw. return rejected("PUBLISH_PREPARATION_FAILED", sanitized(beforeTheWire), startedAt); } + return sendEncoded(destination, profile, encoded, options, startedAt); + } + @Override + public CompletionStage publishEncoded( + MessageDestination destination, + MessageEnvelope message, + PublishOptions options) { + Objects.requireNonNull(destination, "destination must not be null"); + Objects.requireNonNull(message, "message must not be null"); + Objects.requireNonNull(options, "options must not be null"); + + long startedAt = nanoTime.getAsLong(); + DestinationProfile profile; + try { + profile = destinations.require(destination.name()); + requireSupportedOptions(profile, options); + if (!access.mayPublish(destination.name())) { + return rejected( + "PUBLISH_FORBIDDEN", + "this application may not publish to '" + destination.name().value() + "'", + startedAt); + } + requireEncodedEnvelope(message); + } catch (RuntimeException beforeTheWire) { + return rejected("PUBLISH_PREPARATION_FAILED", sanitized(beforeTheWire), startedAt); + } + return sendEncoded(destination, profile, message, options, startedAt); + } + + private CompletionStage sendEncoded( + MessageDestination destination, + DestinationProfile profile, + MessageEnvelope encoded, + PublishOptions options, + long startedAt) { Duration remaining = remainingBudget(options.timeout(), startedAt); if (remaining.isZero() || remaining.isNegative()) { - // The budget was spent resolving and encoding, so nothing has been transmitted and the - // outcome is still definite. Sending anyway would start a message the caller has already - // stopped waiting for. return rejected( "PUBLISH_DEADLINE_EXCEEDED", "the " @@ -204,13 +233,9 @@ public final class DefaultMessagePublisher implements MessagePublisher { transport.publish(new TransportPublishRequest(profile, encoded, options)), remaining) .handle( (result, failure) -> { - // One release per acquisition, whatever happened. A permit that leaks on the - // failure path is a limiter that shrinks by one per failure until it accepts - // nothing. held.close(); admission.complete(destination.name().value()); if (failure != null) { - // The request was on the wire when this failed, so the broker may hold it. PublishResult ambiguous = isDeadline(failure) ? ambiguousResult( @@ -236,6 +261,13 @@ public final class DefaultMessagePublisher implements MessagePublisher { } } + private static void requireEncodedEnvelope(MessageEnvelope message) { + if (!message.contentType().equals(message.payload().contentType())) { + throw new IllegalArgumentException( + "pre-encoded envelope content type must match its encoded payload content type"); + } + } + /** * Refuses options the destination cannot honour, before anything is encoded or sent. * diff --git a/messaging/messaging-runtime-core/src/test/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisherTest.java b/messaging/messaging-runtime-core/src/test/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisherTest.java index 1caad12..5efc0c9 100644 --- a/messaging/messaging-runtime-core/src/test/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisherTest.java +++ b/messaging/messaging-runtime-core/src/test/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisherTest.java @@ -26,6 +26,7 @@ import dev.caskeleton.messaging.policy.MessagingAdmissionController; import dev.caskeleton.messaging.policy.PayloadLimitGuard; import dev.caskeleton.messaging.policy.PayloadPolicy; import dev.caskeleton.messaging.schema.EncodedMessage; +import dev.caskeleton.messaging.schema.EncodedMessagePublisher; import dev.caskeleton.messaging.schema.MessageCodec; import dev.caskeleton.messaging.schema.MessageCodecRegistry; import dev.caskeleton.messaging.security.DestinationAccessPolicy; @@ -85,6 +86,39 @@ class DefaultMessagePublisherTest { .isZero(); } + @Test + @DisplayName("a pre-encoded publish skips codecs but still runs admission, runtime and transport") + void aPreEncodedPublishPreservesWireBytesWithoutBypassingThePipeline() { + SingleCodecRegistry codecs = new SingleCodecRegistry(); + DefaultMessagePublisher publisher = + new DefaultMessagePublisher( + registry(), + allowOrders(), + codecs, + admission, + new FixedRuntimeRegistry(transport), + transport); + byte[] wireBytes = "{\"already\":\"encoded\"}".getBytes(StandardCharsets.UTF_8); + MessageEnvelope encoded = + envelope().withPayload(new EncodedMessage(wireBytes, ContentType.JSON, Optional.empty())); + + PublishResult result = + ((EncodedMessagePublisher) publisher) + .publishEncoded( + new MessageDestination<>( + ORDERS, new MessageType("order.created"), EncodedMessage.class), + encoded, + PublishOptions.defaults()) + .toCompletableFuture() + .join(); + + assertThat(result.completion()).isEqualTo(PublishCompletion.CONFIRMED); + assertThat(codecs.encodes()).isZero(); + assertThat(transport.lastRequest().envelope().payload().bytes()).containsExactly(wireBytes); + assertThat(transport.lastRequest().envelope().payload().contentType()).isEqualTo(ContentType.JSON); + assertThat(admission.inFlight()).isZero(); + } + @Test @DisplayName("an unregistered destination is rejected before anything is encoded") void anUnregisteredDestinationIsRejected() { @@ -431,6 +465,8 @@ class DefaultMessagePublisherTest { private boolean stalled; + private TransportPublishRequest lastRequest; + private void failWith(RuntimeException failure) { this.failure = failure; } @@ -442,6 +478,7 @@ class DefaultMessagePublisherTest { @Override public CompletionStage publish(TransportPublishRequest request) { + this.lastRequest = request; if (failure != null) { return CompletableFuture.failedFuture(failure); } @@ -488,6 +525,10 @@ class DefaultMessagePublisherTest { private int published() { return published.get(); } + + private TransportPublishRequest lastRequest() { + return lastRequest; + } } /** A registry with no installed generation, which is what a rotation gap looks like. */ diff --git a/messaging/messaging-schema-api/src/main/java/dev/caskeleton/messaging/schema/EncodedMessagePublisher.java b/messaging/messaging-schema-api/src/main/java/dev/caskeleton/messaging/schema/EncodedMessagePublisher.java new file mode 100644 index 0000000..94d4d22 --- /dev/null +++ b/messaging/messaging-schema-api/src/main/java/dev/caskeleton/messaging/schema/EncodedMessagePublisher.java @@ -0,0 +1,24 @@ +package dev.caskeleton.messaging.schema; + +import dev.caskeleton.messaging.api.MessageEnvelope; +import dev.caskeleton.messaging.api.destination.MessageDestination; +import dev.caskeleton.messaging.api.publish.PublishOptions; +import dev.caskeleton.messaging.api.publish.PublishResult; +import java.util.concurrent.CompletionStage; + +/** + * Publishes an envelope whose payload has already been encoded by an authoritative application + * contract boundary. + * + *

This is intentionally narrower than the transport SPI. Callers may skip only the codec step; + * destination resolution, access policy, admission, runtime leasing, transport normalization and + * observation remain owned by the platform's central publisher. + */ +@FunctionalInterface +public interface EncodedMessagePublisher { + + CompletionStage publishEncoded( + MessageDestination destination, + MessageEnvelope message, + PublishOptions options); +} diff --git a/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingCoreAutoConfiguration.java b/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingCoreAutoConfiguration.java index 0caded5..89c155b 100644 --- a/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingCoreAutoConfiguration.java +++ b/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingCoreAutoConfiguration.java @@ -436,7 +436,7 @@ public class MessagingCoreAutoConfiguration { */ @Bean @ConditionalOnMissingBean(MessagePublisher.class) - public MessagePublisher messagingPublisher( + public dev.caskeleton.messaging.runtime.DefaultMessagePublisher messagingPublisher( dev.caskeleton.messaging.runtime.DestinationProfileRegistry destinations, dev.caskeleton.messaging.security.DestinationAccessPolicy access, dev.caskeleton.messaging.schema.MessageCodecRegistry codecs, diff --git a/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingStarterOffContractTest.java b/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingStarterOffContractTest.java index 2d15475..2d4f7c4 100644 --- a/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingStarterOffContractTest.java +++ b/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingStarterOffContractTest.java @@ -5,6 +5,7 @@ import static org.assertj.core.api.Assertions.assertThat; import dev.caskeleton.messaging.api.MessageEnvelope; import dev.caskeleton.messaging.api.destination.MessageDestination; import dev.caskeleton.messaging.api.publish.MessagePublisher; +import dev.caskeleton.messaging.schema.EncodedMessagePublisher; import dev.caskeleton.messaging.api.publish.PublishOptions; import dev.caskeleton.messaging.api.publish.PublishResult; import java.util.Set; @@ -187,6 +188,7 @@ class MessagingStarterOffContractTest { + "depend on that leaf.") .hasNotFailed(); assertThat(context).hasSingleBean(MessagePublisher.class); + assertThat(context).hasSingleBean(EncodedMessagePublisher.class); }); }