Merge pull request 'refactor!: 확인 리뷰 수정과 저장소 구조·문서 체계 정리를 합친다' (#2) from refactor/maturity-review-2026-11 into main
This commit is contained in:
@@ -15,7 +15,7 @@ name: messaging-certification
|
||||
on:
|
||||
pull_request:
|
||||
paths:
|
||||
- "src/messaging/**"
|
||||
- "src/platforms/messaging/**"
|
||||
- ".github/workflows/messaging-certification.yml"
|
||||
# Every Gradle job here installs its toolchain through this composite action, so a change to
|
||||
# it changes what this gate runs.
|
||||
@@ -47,5 +47,5 @@ jobs:
|
||||
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2
|
||||
with:
|
||||
name: messaging-broker-certification-evidence
|
||||
path: src/messaging/messaging-kafka/build/messaging-certification/
|
||||
path: src/platforms/messaging/messaging-kafka/build/messaging-certification/
|
||||
if-no-files-found: warn
|
||||
|
||||
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-10
|
||||
- 요약: 메시지 생성부터 브로커 수락, 소비자 정산까지 증거로 다루는 메시징 플랫폼 설계다.
|
||||
- 현재 정본: `docs/messaging/support-matrix.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Messaging Platform 설계서
|
||||
|
||||
- **상태:** 구현 승인용 기준 설계
|
||||
|
||||
@@ -21,6 +21,10 @@ runtime이 admin 자격 증명을 아예 보유하지 않으므로, 침해된 ha
|
||||
- broker authentication 활성
|
||||
- topology auto-create 비활성
|
||||
|
||||
broker 인증서는 `subjectAltName`에 접속 이름을 가져야 한다. hostname verification은 SAN을 보므로, SAN이
|
||||
없는 인증서는 실패하는 것이 맞다. 검사를 끄지 않는다. 키와 인증서는 배포 환경의 PKI가 발급해 실행 때
|
||||
마운트하고, repo에 두지 않는다.
|
||||
|
||||
Kafka는 추가로 `enable.idempotence=true`, `acks=all`,
|
||||
`max.in.flight.requests.per.connection <= 5`, consumer auto-commit 금지.
|
||||
|
||||
|
||||
@@ -27,7 +27,7 @@
|
||||
> `modules.json`은 messaging leaf의 `gradle_path`와 허용 의존성을 관리하지만
|
||||
> `runtime_memberships` 필드는 없다. 실제 런타임 편입은 `app-bootstrap`의 Gradle 의존성과 starter /
|
||||
> auto-configuration 경로가 결정한다. 아래 등급은 "무엇이 증명되었는가"를 말하며 런타임 편입 여부와
|
||||
> 같은 축이 아니다. 자세한 composition/cutover 상태는 `src/messaging/CLAUDE.md`가 소유한다.
|
||||
> 같은 축이 아니다. 자세한 composition/cutover 상태는 `src/platforms/messaging/CLAUDE.md`가 소유한다.
|
||||
|
||||
## 브로커 등급
|
||||
|
||||
|
||||
+8
-8
@@ -26,21 +26,21 @@ leaf의 정확한 id는 registry에서 읽는다. family는 **디렉터리 이
|
||||
`InboxRepository`)를, `messaging-reliability`가 그 port만 보는 relay·consumer 로직(stdlib)을,
|
||||
`messaging-reliability-jdbc-postgresql`이 port의 관계형 구현과 migration(`V1001..V1005`, `V1101`)을
|
||||
갖는다. 예전에는 `outbox-jdbc-postgresql` 하나가 relay 로직과 PG repository와 admin journal을 함께
|
||||
가졌고 inbox도 같은 모양이었다(S7-#5b). 구현 leaf가 `jdbc-postgresql`로 명명된 이유: 구현은 Spring
|
||||
가졌고 inbox도 같은 모양이었다(2026-09-25 리뷰 후속 작업에서 나눴다). 구현 leaf가 `jdbc-postgresql`로 명명된 이유: 구현은 Spring
|
||||
JDBC이고 SQL은 `jsonb` · `FOR UPDATE SKIP LOCKED` · `ON CONFLICT` · `TIMESTAMPTZ`로 PostgreSQL
|
||||
전용이다. `jpa`라는 이름은 사용하지 않는 기술을 광고하고, vendor 중립 port가 어디 있는지도 숨겼다.
|
||||
|
||||
### 공용 다이제스트 헬퍼를 복사해 두는 이유 (review 2026-11-01 01-11)
|
||||
### 공용 다이제스트 헬퍼를 복사해 두는 이유
|
||||
|
||||
`messaging-admin`(`HmacApprovalVerifier`, `PlanDigest`)과 `messaging-claim-check`
|
||||
(`ClaimCheckIntegrityGuard`)는 SHA-256·HMAC-SHA256 계산을 자기 안에 둔다. 템플릿의
|
||||
`shared-contract` `digest/Sha256`·`HmacSha256`을 쓰지 않는 것은 의도다. 이 family는 이 애플리케이션의
|
||||
계층이 아니라 자기 API·SPI·composition을 가진 다른 제품이고(MSG-023 §6.2), `messaging:*` leaf는
|
||||
계층이 아니라 자기 API·SPI·composition을 가진 다른 제품이고(2026-08-14 messaging 모듈 리뷰 뒤 소유자가 정한 배치), `messaging:*` leaf는
|
||||
`domain-core`·`application-core`·`shared-contract` 어느 타입에도 의존하지 않는다. 헬퍼 하나 때문에
|
||||
registry edge를 주면 그 경계가 깨진다. 복사본을 고칠 때(키 길이 검사, constant-time 비교 등)는
|
||||
`shared-contract`의 정본과 같은 규칙인지 함께 본다.
|
||||
|
||||
### Publish retryability of authentication and authorization (review 2026-11-01 06-01)
|
||||
### Publish retryability of authentication and authorization
|
||||
|
||||
이 제품 안에는 같은 category에 대한 재시도 규칙이 둘 있다. 의도다.
|
||||
|
||||
@@ -63,7 +63,7 @@ registry edge를 주면 그 경계가 깨진다. 복사본을 고칠 때(키 길
|
||||
번역하는 것. 버린 이유: `retryable`은 이 제품이 "같은 레코드를 나중에 다시 보내면 받아질 수 있나"를 말하는
|
||||
자리다. bridge가 category로 그 판단을 다시 하면 같은 사실을 제품과 bridge가 따로 정하고, 이 제품의
|
||||
`PublishResult`를 읽는 다른 호출자는 bridge와 다른 답을 본다. 대신 이 제품 주석은 소비자 이름(application
|
||||
relay, `composition:outbox-relay`)을 부르지 않는다 — "flag를 믿는 publisher"로 쓴다(재리뷰 2026-11-03 RR-05-07).
|
||||
relay, `composition:outbox-relay`)을 부르지 않는다 — "flag를 믿는 publisher"로 쓴다(2026-11-03).
|
||||
|
||||
## Public surface 정책
|
||||
|
||||
@@ -95,7 +95,7 @@ RabbitMQ·Pulsar·NATS·Kafka Share·Spring Cloud Stream bridge leaf와 Debezium
|
||||
새 leaf를 application에 채택할 때는 starter 또는 composition dependency와 architecture edge policy,
|
||||
qualification/support 상태를 함께 변경한다.
|
||||
|
||||
## application이 이 family에 도달하는 경로 (MSG-015, cutover 완료)
|
||||
## application이 이 family에 도달하는 경로 (cutover 완료)
|
||||
|
||||
리뷰(`docs/reviews/2026-08-14-messaging-module-code-review.md` §6.1·§6.3)가 정한
|
||||
`application-owned port → platform anti-corruption bridge → platform` 경로는 이제 존재한다.
|
||||
@@ -110,7 +110,7 @@ lease/transport/outcome normalization/observation은 platform 중앙 publish pat
|
||||
package는 `messaging-core-api`만 보며 concrete runtime/transport/Kafka 타입을
|
||||
직접 보지 않는다.
|
||||
|
||||
**MSG-015 cutover는 끝났다(2026-09-28, 소유자 결정 7).** application의 outbox append는 canonical
|
||||
**application bridge cutover는 2026-09-28에 끝났다(2026-09-25 소유자 결정).** application의 outbox append는 canonical
|
||||
`OutboxAppendPort` 하나이고, relay는 claim한 row의 validated event를 이 bridge로만 보낸다. legacy
|
||||
`OutboxEvent`·`LegacyOutboxAppendPort`와 `MessageBroker → KafkaSender` R0 경로(TLS/SASL을 적용하지
|
||||
않던 두 번째 producer)는 삭제했다. 남은 Kafka producer는 platform의 것 하나이고, broker security
|
||||
@@ -137,7 +137,7 @@ adapter를 Experimental → Stable로 올릴 때 필요한 것 (`docs/messaging/
|
||||
3. capability 선언이 코드에서 파생된다 — `MessagingCapabilities`에 손으로 `true`를 쓰는 것은
|
||||
증거가 아니다.
|
||||
4. publish 실패 분류가 typed signal에서만 나온다. exception class 이름 substring 판정은
|
||||
Experimental에서도 금지다(MSG-022).
|
||||
Experimental에서도 금지다.
|
||||
5. unknown failure의 기본값이 `AMBIGUOUS`다. `REJECTED`는 전송이 시작되지 않았다는 typed 증거가
|
||||
있을 때만.
|
||||
|
||||
|
||||
@@ -98,7 +98,7 @@ tasks.register('verifyMessagingCertificationEvidence') {
|
||||
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')
|
||||
def committed = rootProject.file('platforms/messaging/messaging-testkit/src/main/resources/messaging/broker-certification-evidence.jsonl')
|
||||
inputs.file(produced)
|
||||
inputs.file(committed)
|
||||
doLast {
|
||||
|
||||
+2
-2
@@ -73,8 +73,8 @@ public final class KafkaPublishFailureClassifier {
|
||||
*
|
||||
* <p>This flag departs from {@link FailureDescriptor#defaultRetryable} on purpose, for publish
|
||||
* only: that default says an authentication or authorization failure is not retried, and it still
|
||||
* governs consumption, where the retry engine requires both. See {@code src/messaging/CLAUDE.md}
|
||||
* "Publish retryability of authentication and authorization".
|
||||
* governs consumption, where the retry engine requires both. See {@code
|
||||
* src/platforms/messaging/CLAUDE.md} "Publish retryability of authentication and authorization".
|
||||
*/
|
||||
private static boolean mayPassOnRetry(Throwable cause) {
|
||||
return cause instanceof AuthenticationException || cause instanceof AuthorizationException;
|
||||
|
||||
+40
-4
@@ -7,11 +7,14 @@ import dev.caskeleton.messaging.api.error.MessageBackpressureException;
|
||||
import dev.caskeleton.messaging.api.error.MessageTooLargeException;
|
||||
import java.time.Duration;
|
||||
import java.util.List;
|
||||
import java.util.concurrent.atomic.AtomicReference;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
class MessagingAdmissionControllerTest {
|
||||
|
||||
private static final String DESTINATION = "order.created";
|
||||
private static final String OTHER_DESTINATION = "invoice.issued";
|
||||
private static final Duration WAITER_BOUND = Duration.ofSeconds(30);
|
||||
|
||||
private static MessagingAdmissionController controller(int limit) {
|
||||
return new MessagingAdmissionController(
|
||||
@@ -182,16 +185,49 @@ class MessagingAdmissionControllerTest {
|
||||
void aWaitingCallerIsAdmittedOnceAPermitIsReturned() throws InterruptedException {
|
||||
MessagingAdmissionController controller =
|
||||
new MessagingAdmissionController(
|
||||
new PayloadLimitGuard(PayloadPolicy.defaults()),
|
||||
new InFlightLimiter(1, Duration.ofSeconds(2)));
|
||||
new PayloadLimitGuard(PayloadPolicy.defaults()), new InFlightLimiter(1, WAITER_BOUND));
|
||||
controller.admit(DESTINATION, 100);
|
||||
AtomicReference<RuntimeException> refused = new AtomicReference<>();
|
||||
// Another destination, so only the process-wide permit is contested. A second publish to
|
||||
// DESTINATION is refused at once by its own ceiling (equal to the process limit here) and
|
||||
// never waits.
|
||||
Thread waiter =
|
||||
new Thread(
|
||||
() -> {
|
||||
try {
|
||||
controller.admit(OTHER_DESTINATION, 100);
|
||||
} catch (RuntimeException refusal) {
|
||||
refused.set(refusal);
|
||||
}
|
||||
});
|
||||
|
||||
Thread waiter = new Thread(() -> controller.admit(DESTINATION, 100));
|
||||
waiter.start();
|
||||
awaitQueuedOnAPermit(waiter, refused);
|
||||
controller.complete(DESTINATION);
|
||||
waiter.join(Duration.ofSeconds(5).toMillis());
|
||||
waiter.join(WAITER_BOUND.toMillis());
|
||||
|
||||
assertThat(refused.get()).as("the waiter was refused instead of admitted").isNull();
|
||||
assertThat(waiter.isAlive()).isFalse();
|
||||
assertThat(controller.inFlight()).isEqualTo(1);
|
||||
assertThat(controller.inFlight(OTHER_DESTINATION)).isEqualTo(1);
|
||||
}
|
||||
|
||||
/**
|
||||
* Waits until {@code waiter} is parked in the limiter's bounded wait, so the permit is returned
|
||||
* to a caller that is already queued rather than to one that has not arrived yet.
|
||||
*/
|
||||
private static void awaitQueuedOnAPermit(Thread waiter, AtomicReference<RuntimeException> refused)
|
||||
throws InterruptedException {
|
||||
long deadline = System.nanoTime() + WAITER_BOUND.toNanos();
|
||||
while (waiter.getState() != Thread.State.TIMED_WAITING
|
||||
&& waiter.isAlive()
|
||||
&& System.nanoTime() < deadline) {
|
||||
Thread.sleep(1);
|
||||
}
|
||||
assertThat(waiter.getState())
|
||||
.as(
|
||||
"the waiter must be queued on the permit before it is returned (refused: %s)",
|
||||
refused.get())
|
||||
.isEqualTo(Thread.State.TIMED_WAITING);
|
||||
}
|
||||
}
|
||||
|
||||
+4
-4
@@ -1,4 +1,4 @@
|
||||
{"adapter":"messaging-kafka","brokerImage":"apache/kafka:4.1.0","scenario":"confirm-timeout","testId":"KafkaBrokerCertificationIT#aConfirmThatNeverArrivesIsReportedAsAmbiguousAndTheRecordIsThere","outcome":"AMBIGUOUS","gitCommit":"e98b56eb03ecab588c21fd1e7dbcaa493c1d8645","observedAt":"2026-08-19T14:21:30.826332993Z"}
|
||||
{"adapter":"messaging-kafka","brokerImage":"apache/kafka:4.1.0","scenario":"connection-cut-after-write","testId":"KafkaBrokerCertificationIT#aConnectionCutAfterTheWriteIsReportedAsAmbiguous","outcome":"AMBIGUOUS","gitCommit":"e98b56eb03ecab588c21fd1e7dbcaa493c1d8645","observedAt":"2026-08-19T14:21:34.906464945Z"}
|
||||
{"adapter":"messaging-kafka","brokerImage":"apache/kafka:4.1.0","scenario":"high-latency","testId":"KafkaBrokerCertificationIT#latencyBeyondThePublishDeadlineIsReportedAsAmbiguous","outcome":"AMBIGUOUS","gitCommit":"e98b56eb03ecab588c21fd1e7dbcaa493c1d8645","observedAt":"2026-08-19T14:21:21.870705263Z"}
|
||||
{"adapter":"messaging-kafka","brokerImage":"apache/kafka:4.1.0","scenario":"settlement-lost","testId":"KafkaBrokerCertificationIT#aDeliveryLostBeforeSettlementIsRedelivered","outcome":"REDELIVERED","gitCommit":"e98b56eb03ecab588c21fd1e7dbcaa493c1d8645","observedAt":"2026-08-19T14:21:42.058283607Z"}
|
||||
{"adapter":"messaging-kafka","brokerImage":"apache/kafka@sha256:bff074a5d0051dbc0bbbcd25b045bb1fe84833ec0d3c7c965d1797dd289ec88f","scenario":"confirm-timeout","testId":"KafkaBrokerCertificationIT#aConfirmThatNeverArrivesIsReportedAsAmbiguousAndTheRecordIsThere","outcome":"AMBIGUOUS","gitCommit":"8d69e599a376e4db29fdf7b96e06fa457ba6ace1","observedAt":"2026-11-07T04:05:39.857063221Z"}
|
||||
{"adapter":"messaging-kafka","brokerImage":"apache/kafka@sha256:bff074a5d0051dbc0bbbcd25b045bb1fe84833ec0d3c7c965d1797dd289ec88f","scenario":"connection-cut-after-write","testId":"KafkaBrokerCertificationIT#aConnectionCutAfterTheWriteIsReportedAsAmbiguous","outcome":"AMBIGUOUS","gitCommit":"8d69e599a376e4db29fdf7b96e06fa457ba6ace1","observedAt":"2026-11-07T04:05:43.917138801Z"}
|
||||
{"adapter":"messaging-kafka","brokerImage":"apache/kafka@sha256:bff074a5d0051dbc0bbbcd25b045bb1fe84833ec0d3c7c965d1797dd289ec88f","scenario":"high-latency","testId":"KafkaBrokerCertificationIT#latencyBeyondThePublishDeadlineIsReportedAsAmbiguous","outcome":"AMBIGUOUS","gitCommit":"8d69e599a376e4db29fdf7b96e06fa457ba6ace1","observedAt":"2026-11-07T04:05:29.018486328Z"}
|
||||
{"adapter":"messaging-kafka","brokerImage":"apache/kafka@sha256:bff074a5d0051dbc0bbbcd25b045bb1fe84833ec0d3c7c965d1797dd289ec88f","scenario":"settlement-lost","testId":"KafkaBrokerCertificationIT#aDeliveryLostBeforeSettlementIsRedelivered","outcome":"REDELIVERED","gitCommit":"8d69e599a376e4db29fdf7b96e06fa457ba6ace1","observedAt":"2026-11-07T04:05:51.014447Z"}
|
||||
|
||||
+3
-3
@@ -34,8 +34,8 @@ import org.junit.jupiter.api.Test;
|
||||
*
|
||||
* <p>So the rule is one-directional and mechanical: a vendor library named in a public or protected
|
||||
* signature is declared {@code api}; one used only behind private members stays {@code
|
||||
* implementation}. {@code src/messaging/CLAUDE.md} states it as policy — this holds it to the
|
||||
* source so the two cannot drift.
|
||||
* implementation}. {@code src/platforms/messaging/CLAUDE.md} states it as policy — this holds it to
|
||||
* the source so the two cannot drift.
|
||||
*
|
||||
* <p>The libraries checked are the ones an adopter would otherwise have to reverse-engineer into
|
||||
* their own build: broker clients, codec libraries, the metrics registry, the reactive facade.
|
||||
@@ -345,7 +345,7 @@ class MessagingPublicSurfaceContractTest {
|
||||
}
|
||||
|
||||
private static List<Path> messagingLeaves() {
|
||||
Path family = repositoryRoot().resolve("src/messaging");
|
||||
Path family = repositoryRoot().resolve("src/platforms/messaging");
|
||||
try (Stream<Path> children = Files.list(family)) {
|
||||
return children
|
||||
.filter(Files::isDirectory)
|
||||
|
||||
Reference in New Issue
Block a user