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절
This commit is contained in:
DongHyeonka
2026-11-08 17:11:33 +09:00
parent 5af9415587
commit 7dc5725fe7
40 changed files with 102 additions and 1297 deletions
+1 -1
View File
@@ -17,7 +17,7 @@ Java 21 + Spring Boot Gradle 멀티모듈 Clean Architecture 템플릿이다(버
- Gradle 루트는 `src/`다. leaf 목록·경로·Gradle path·허용 의존의 정본은 registry `src/config/architecture/modules.json`이다. 문서는 leaf 개수를 적지 않는다.
- 방향: `app-bootstrap → adapter:inbound:*·adapter:outbound:* → application-core → domain-core`, 실행 모듈 → `shared-contract`. 개별 edge는 registry만 정한다.
- 지역 규칙은 작업 파일과 가장 가까운 폴더의 `AGENTS.md`다(leaf, family, `src/build-logic`). 테스트·설정·Docker·문서처럼 폴더를 가로지르는 규칙은 `.claude/rules/`다.
- 저장소 루트와 `src/` 최상위에는 정해진 것만 둔다(허용 목록은 `scripts/check-repo-layout.py`). `src/platforms/*`는 계층이 아닌 들여온 제품, `src/composition/*`는 조립만 한다.
- 저장소 루트와 `src/` 최상위에는 정해진 것만 둔다(허용 목록은 `scripts/check-repo-layout.py`). 계층이 아닌 라이브러리는 이 repo에 두지 않고 별도 repo에서 버전으로 받는다(`docs/work/reference/related-repos.md`). `src/composition/*`는 조립만 한다.
- capability는 `src/app-bootstrap/build.gradle`의 `runtimeOnly` 한 줄로 켜고 끈다. 기준은 `docs/manual/10-capabilities.md`. 문서 위치 규칙은 `docs/README.md`.
## 맡은 일
+1 -2
View File
@@ -15,7 +15,7 @@ ca-skeleton은 Java 21과 Spring Boot로 만든 Gradle 멀티모듈 백엔드
| `compose/` | `compose.yaml`이 마운트하는 보조 파일(Keycloak realm, Redis ACL, MinIO 초기화) | [compose/redis/acl/README.md](compose/redis/acl/README.md) |
| `.github/` | workflow, 공용 action, PR 양식, 의존성 취약점 정책 | [.github/dependency-vulnerability-policy.md](.github/dependency-vulnerability-policy.md) |
`src/` 아래 폴더는 계층 leaf, 조립, 들여온 제품, Gradle 표준 폴더로 나뉜다. leaf는 Gradle 프로젝트 하나이고, leaf 목록·경로·허용 의존은 registry `src/config/architecture/modules.json`이 정한다.
`src/` 아래 폴더는 계층 leaf, 조립, Gradle 표준 폴더로 나뉜다. leaf는 Gradle 프로젝트 하나이고, leaf 목록·경로·허용 의존은 registry `src/config/architecture/modules.json`이 정한다.
| 폴더 | 책임 | 기본 조립에 들어가나 |
| --- | --- | --- |
@@ -27,7 +27,6 @@ ca-skeleton은 Java 21과 Spring Boot로 만든 Gradle 멀티모듈 백엔드
| `adapter/outbound/` | port 뒤의 구현: 영속성(JPA·MongoDB), Redis, 메시징, 알림, 객체 저장소, 파일 서버, HTTP client, identifier, 공용 기반(support) | `support`·`identifier`만 들어간다 |
| `composition/` | 조립만 하는 leaf: 서비스 런타임 배선, outbox relay, 멱등성 executor, durable operation, 알림·파일 서버 플랫폼 | `service-runtime`·`outbox-relay`·`idempotency`·`durable-operation`이 들어간다. 뒤의 셋은 필요한 port가 생기기 전에는 아무것도 만들지 않는다 |
| `app-bootstrap/` | Spring Boot 진입점과 조립 루트(composition root, 모든 모듈을 엮는 곳) | 들어간다 |
| `platforms/` | 들여온 제품: `messaging`(메시징 플랫폼). gRPC 플랫폼 라이브러리는 2026-11-08에 별도 repo `grpc-library`로 옮겼다([관련 저장소](docs/work/reference/related-repos.md)) | 들어가지 않는다. adapter를 거쳐서만 닿는다 |
| `build-logic/`, `config/`, `gradle/` | 빌드 규칙(convention plugin), 빌드 전체 도구 설정과 registry, wrapper와 버전 카탈로그 | 빌드 도구 |
의존은 항상 바깥에서 안으로 흐른다. adapter가 core의 port에 의존하고, core는 adapter를 모른다.
-1
View File
@@ -46,7 +46,6 @@ capability(부가 기능) 하나의 지원 범위, 설정, 보안, 운영, 마
| `fileserver/` | 파일 서버 |
| `httpclient/` | 외부 HTTP 호출(HTTP client 플랫폼) |
| `jpa/` | JPA·PostgreSQL 영속성 |
| `messaging/` | 메시징 adapter |
| `mongodb/` | MongoDB 문서 영속성 |
| `mongodb/advanced/` | MongoDB 고급 기능(암호화, 멀티 테넌시, 샤딩). 설정 키가 아니라 라이브러리 API로 켠다 |
| `mongodb/runbooks/` | MongoDB 장애 대응 |
+1 -1
View File
@@ -29,7 +29,7 @@ lanes and CI; it is not a deployment artifact.
| --- | --- | --- | --- | --- | --- |
| Relational persistence (JPA/PostgreSQL) | `ca-skeleton.persistence-jpa.enabled` / `APP_PERSISTENCE_JPA_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:persistence-jpa')`) | yes | Not in the default composition. The one line brings everything — its own `AutoConfiguration.imports` (`PersistenceJpaAutoConfiguration`, `PersistenceJpaRuntimeConfig`, `JpaStartupAutoConfiguration`), its environment handling (`JpaActivationEnvironmentPostProcessor`, `spring.factories`: readiness `db` while on; with `false` it also excludes Boot's JDBC, Hibernate, Spring Data JPA and Flyway auto-configuration, so no DataSource is bound), the startup guards (Flyway strategy, datasource/OSIV/DDL/pool/TLS/vendor checks, exit codes unchanged) and its settings (`config/module-defaults/persistence-jpa.yml`). `persistence-jpa:PersistenceJpaCapabilityAssemblyTest` proves the module assembles on its own; the `postgresql*IntegrationTest` readiness lanes, run by `integration-main.yml` → `integration-check` (`:integrationCheck`), qualify it against PostgreSQL. `bootRunH2` adds the module to its own classpath only. |
| Document persistence (MongoDB) | `ca-skeleton.persistence-mongo.enabled` / `APP_PERSISTENCE_MONGO_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:persistence-mongo')`) | yes | On when present; `false` also excludes Boot's Mongo auto-configuration (`MongoCapabilityActivationTest`). The connection-source rule (`SPRING_MONGODB_URI` or the selected profile's `uri-secret`) is checked by the module's own `MongoDefaultsEnvironmentPostProcessor`. Six container lanes (`mongoReplicaSetTest`, `mongoFailoverTest`, …), run by `integration-main.yml` → `integration-check` (`:integrationCheck`) |
| Messaging (Kafka) | `app.messaging.enabled` / `APP_MESSAGING_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:messaging-kafka')`, which brings the application bridge, the legacy `KafkaSender` seam and the vendored platform with its Kafka transport) | Kafka only | On when present (`KafkaCapabilityActivationTest`). `messaging-kafka:messagingCertificationTest` behind `verifyMessagingCertificationEvidence`, run by `messaging-certification.yml`; the starter's `integrationTest` is the live Kafka round trip. Kafka is the only registered broker; the RabbitMQ broker keys were removed (no transport). |
| Messaging (Kafka) | `app.messaging.enabled` / `APP_MESSAGING_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:messaging-kafka')`, which brings the application bridge and the messaging library `dev.cakit.messaging` (messaging-library repo, catalog `messagingLibrary`) with its Kafka transport) | Kafka only | On when present (`KafkaCapabilityActivationTest`). The application's own publish and consume paths run against a live Kafka in `messagingKafkaRelayIntegrationTest` and `messagingInboxRedeliveryIntegrationTest`. The library's broker certification (`verifyMessagingCertificationEvidence`) runs in the messaging-library repo's main stage since 2026-11-08. Kafka is the only registered broker; the RabbitMQ broker keys were removed (no transport). |
| Redis capabilities (cache / rate-limit / lease / idempotency) | `app.redis.enabled` / `APP_REDIS_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:cache-redis')`, which brings `redis-runtime`) | yes | `cache-redis:redisContainerContractTest` (Testcontainers Redis, `integrationCheck`); `cache-redis:redisTopologyTest`, run by `redis-sdk-topology.yml`. Not in the default composition. On when present; `false` contributes no Redis bean — no settings, client, connection, thread or health contributor. The module owns its readiness contribution (`RedisReadinessGroupPostProcessor`, `spring.factories`) and its settings (`config/module-defaults/cache-redis.yml`: `app.redis.enabled`, `app.rate-limit.*`, the Redis `ca-skeleton.capabilities.*`). No `app-bootstrap` main source names a Redis type. |
| Request idempotency | `APP_IDEMPOTENCY_PROVIDER` (`disabled` \| `redis` \| `postgresql`; a selector, not an on/off key) | yes | yes | Redis and PostgreSQL | One generation: the application `IdempotencyExecutor`, built once by `composition:idempotency` (`IdempotencyAutoConfiguration`) over the one store the selected provider contributes (`cache-redis` or `persistence-jpa`); startup is refused unless exactly one store exists. `app-bootstrap`이 그 모듈을 `runtimeOnly` 한 줄로 받고, 다른 조립은 없다. Redis is covered by the row above. PostgreSQL has `persistence-jpa:postgresqlIdempotencyIntegrationTest`, run by `integration-main.yml` → `integration-check` (`:integrationCheck`). The `postgresql` provider refuses a non-PostgreSQL data source, so `bootRunH2` uses `disabled` or `redis`. Each store comes with its module: `postgresql` needs the persistence-jpa line, `redis` the cache-redis one. |
| Transactional outbox relay | `ca-skeleton.outbox.enabled` / `APP_OUTBOX_ENABLED`, `false` (+ `APP_OUTBOX_RELAY_ENABLED`, `false`; persistence-jpa settings) | yes | yes (with the persistence-jpa line; the scheduler also needs the messaging-kafka line) | yes | The store and its settings are persistence-jpa's; the relay (`OutboxConfig`) is application composition in `app-bootstrap` because a driven adapter must not build or call a use case. It turns on only when an `OutboxStorePort` bean exists, and the scheduler only when an `OutboxMessagePublishPort` does (the messaging bridge), each ordered after its contributor by `afterName` — so an environment with no publisher keeps its PENDING rows. The bridge registers no stand-in publisher: a present-and-enabled bridge with a blank broker and no canonical transport is refused at startup. `postgresqlLegacyOutboxConcurrentRelayIntegrationTest` qualifies claim/fencing against PostgreSQL. |
@@ -4,7 +4,7 @@
- 상태: 채택
- 작성일: 2026-07-28
- 요약: 메시징을 운영 가능한 capability로 올리는 상세 설계다.
- 현재 정본: `docs/messaging/support-matrix.md`
- 현재 정본: `docs/manual/09-outbox-events.md`
<!-- 머리 블록 끝 -->
# Messaging Production Capability Deep Design
@@ -4,7 +4,7 @@
- 상태: 채택
- 작성일: 2026-08-10
- 요약: 메시지 생성부터 브로커 수락, 소비자 정산까지 증거로 다루는 메시징 플랫폼 설계다.
- 현재 정본: `docs/messaging/support-matrix.md`
- 현재 정본: 없음 — 메시징 플랫폼은 2026-11-08에 별도 repo messaging-library(Maven group dev.cakit.messaging)로 옮겼다. 지금 동작은 그 repo의 docs/messaging/support-matrix.md다
<!-- 머리 블록 끝 -->
# Messaging Platform 설계서
@@ -4,7 +4,7 @@
- 상태: 확인 안 함
- 작성일: 2026-09-18
- 요약: 애플리케이션 전용 브로커 이음매를 메시징 플랫폼으로 가는 bridge 하나로 바꾸는 설계다.
- 현재 정본: `docs/messaging/support-matrix.md`
- 현재 정본: `docs/manual/09-outbox-events.md`
<!-- 머리 블록 끝 -->
# Messaging Platform Bridge Design
+1 -1
View File
@@ -4,7 +4,7 @@
- 상태: 보관
- 작성일: 2026-08-13
- 요약: 메시징 설계 패키지가 처음 납품됐을 때의 안내다. 본문 문서는 docs/design과 docs/history/plans에 있다.
- 현재 정본: `docs/messaging/support-matrix.md`
- 현재 정본: 없음 — 메시징 플랫폼은 2026-11-08에 별도 repo messaging-library(Maven group dev.cakit.messaging)로 옮겼다. 지금 동작은 그 repo의 docs/messaging/support-matrix.md다
<!-- 머리 블록 끝 -->
> **보존 안내** — 이 파일은 저장소 루트 `messaging-superpowers-package/` 에 있던 납품 패키지의 README다.
@@ -4,7 +4,7 @@
- 상태: 보관
- 작성일: 2026-08-13
- 요약: 메시징 설계 패키지를 받을 때 한 정적 검증 결과다.
- 현재 정본: `docs/messaging/support-matrix.md`
- 현재 정본: 없음 — 메시징 플랫폼은 2026-11-08에 별도 repo messaging-library(Maven group dev.cakit.messaging)로 옮겼다. 지금 동작은 그 repo의 docs/messaging/support-matrix.md다
<!-- 머리 블록 끝 -->
# Messaging Superpowers 문서 정적 검증
@@ -4,7 +4,7 @@
- 상태: 확인 안 함
- 작성일: 2026-07-28
- 요약: typed 통합 이벤트에서 시작하는 첫 운영 기준 메시징 경로(R2 polling producer)를 만드는 실행 계획이다.
- 현재 정본: `docs/messaging/support-matrix.md`
- 현재 정본: `docs/manual/09-outbox-events.md`
<!-- 머리 블록 끝 -->
# Messaging First R2 Polling Producer Implementation Plan
@@ -4,7 +4,7 @@
- 상태: 확인 안 함
- 작성일: 2026-08-10
- 요약: 메시징 플랫폼(증거 기반 발행, 중복 안전 소비, Kafka·RabbitMQ, outbox·inbox)을 만드는 실행 계획이다.
- 현재 정본: `docs/messaging/support-matrix.md`
- 현재 정본: 없음 — 메시징 플랫폼은 2026-11-08에 별도 repo messaging-library(Maven group dev.cakit.messaging)로 옮겼다. 지금 동작은 그 repo의 docs/messaging/support-matrix.md다
<!-- 머리 블록 끝 -->
# Messaging Platform Implementation Plan
@@ -4,7 +4,7 @@
- 상태: 끝남
- 작성일: 2026-09-18
- 요약: 통합 이벤트 발행 경계를 메시징 플랫폼 bridge에 잇는 실행 계획이다.
- 현재 정본: `docs/messaging/support-matrix.md`
- 현재 정본: `docs/manual/09-outbox-events.md`
<!-- 머리 블록 끝 -->
# Messaging Platform Bridge Implementation Plan
+1 -1
View File
@@ -105,7 +105,7 @@ client가 같은 이름의 역할을 정의해도 이 서비스 권한이 되지
| 시스템 호출자만 | inbound adapter가 그 클래스에 의존하면 빌드 실패. `@SystemCaller(reason = "...")`를 단 클래스와 그 안에 중첩된 클래스만 예외 | `ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`(`ApplicationBoundaryArchitectureTest`) |
| 표시 검사 | `@SystemCaller` 클래스와 그 안에 중첩된 클래스는 `..adapter.inbound.messaging..`·`..adapter.inbound.scheduler..`에만 있고, 사용자 전송 타입(controller·JAX-RS·GraphQL·STOMP mapping과 channel interceptor·gRPC·servlet)에 의존하지 않는다 | `SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS`(같은 파일) |
| 전송 → 시스템 호출자 금지 | 사용자 전송 클래스가 `@SystemCaller`나, 그 클래스가 구현·상속하는 프로젝트 타입(작업의 인터페이스 등)에 의존하면 빌드 실패. 중간 클래스를 거쳐도 잡는다. 사용자 전송 클래스는 넷이다. ① 사용자 전송 패키지에 있는 클래스. ② 설정(`@Configuration`·`@AutoConfiguration`) 클래스 자신이 요청 처리기 타입(함수형 `RouterFunction`·`HandlerFunction`, `@RestController`·`@RequestMapping`, servlet·`Filter`·`HandlerInterceptor`, `WebSocketHandler`, GraphQL `DataFetcher`·`RuntimeWiringConfigurer`, gRPC `BindableService`·`ServerInterceptor`, STOMP `ChannelInterceptor`·`ExecutorChannelInterceptor` 등)에 의존하는 것. 요청 처리 코드를 설정에 직접 쓴 경우와 등록만 한 경우가 모두 든다. channel interceptor를 구현한 설정은 프레임마다 자기 메서드가 돈다. interceptor를 `@Bean`으로 내놓는 설정은 route를 등록하는 설정과 같다. 함수형 route나 data fetcher를 람다로 쓰면 그 코드가 설정 클래스의 메서드로 컴파일되어 설정이 곧 endpoint다. 처리 코드를 다른 클래스에 두고 메서드 참조로 등록만 해도(`route().GET("/orders", orders::list)`) 설정은 route builder에 의존한다. 클래스 의존으로는 등록과 처리 코드를 가를 수 없어서 둘 다 사용자 전송으로 센다. ③ 설정 안에 중첩된 클래스 가운데 사용자 전송 타입에 의존하는 것. 중첩된 JAX-RS 자원·`@ServerEndpoint`, `configureClientInboundChannel`에서 등록하는 STOMP channel interceptor(익명 클래스여도, STOMP 헤더를 읽지 않아도)도 여기서 잡힌다. 설정용 타입(`WebMvcConfigurer`·`WebSocketConfigurer`·STOMP broker 설정과 그 registry, CORS 설정, `RequestMethod`)에만 의존하는 중첩 클래스는 설정의 일부로 본다. inbound channel의 thread 수만 정하는 설정도 설정용이다. ④ 그 밖의 클래스 가운데 사용자 전송 타입에 의존하는 것. 사용자 전송 패키지 밖에 둔 channel interceptor가 여기에 든다. 그래서 handler를 bean으로 등록하는 설정은 같은 클래스에서 `WebMvcConfigurer`(설정 필드를 읽는 익명 클래스여도)·CORS 설정·controller bean을 함께 만들어도 걸리지 않는다. 같은 클래스에 "지금 실행" route·data fetcher·interceptor를 쓰거나, route를 등록하거나, 안에 중첩한 endpoint가 작업을 부르면(설정의 메서드를 거쳐 불러도) 걸린다. route·data fetcher·interceptor 등록은 handler bean을 만드는 설정과 다른 설정에 둔다. 설정이 만드는 controller는 controller 자신이 검사받는다 | `USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`(같은 파일) |
| 프로젝트 밖 상위 타입 금지 | `@SystemCaller` 클래스와 그 안에 중첩된 클래스(익명·지역 클래스와 예외 제외)는 프로젝트(`dev.caskeleton..`) 밖의 클래스·인터페이스를 상속·구현하지 않는다. `Runnable`은 누구나 의존하는 타입이라, endpoint가 작업을 `Runnable`로 주입받아도 위 규칙이 다른 사용과 구별하지 못하기 때문이다. 메시지 handler의 `MessageHandler<T>`는 프로젝트 타입이라 된다. record·enum은 언어가 붙이는 상위 타입(`Record`, `Enum`과 `Enum`이 구현하는 `Comparable`·`Serializable`·`Constable`)만은 가져도 된다. 그래서 handler 안의 파싱 결과 record, 결과 enum, 독(poison) 메시지 예외, record로 쓴 handler는 통과하고, `Runnable`을 구현한 record는 걸린다 | `SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES`(같은 파일) |
| 프로젝트 밖 상위 타입 금지 | `@SystemCaller` 클래스와 그 안에 중첩된 클래스(익명·지역 클래스와 예외 제외)는 프로젝트(`dev.caskeleton..`와 소유자의 별도 repo 라이브러리 `dev.cakit..`) 밖의 클래스·인터페이스를 상속·구현하지 않는다. `Runnable`은 누구나 의존하는 타입이라, endpoint가 작업을 `Runnable`로 주입받아도 위 규칙이 다른 사용과 구별하지 못하기 때문이다. 메시지 handler의 `MessageHandler<T>`(메시징 라이브러리 `dev.cakit.messaging`)는 프로젝트 타입으로 쳐서 된다. record·enum은 언어가 붙이는 상위 타입(`Record`, `Enum`과 `Enum`이 구현하는 `Comparable`·`Serializable`·`Constable`)만은 가져도 된다. 그래서 handler 안의 파싱 결과 record, 결과 enum, 독(poison) 메시지 예외, record로 쓴 handler는 통과하고, `Runnable`을 구현한 record는 걸린다 | `SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES`(같은 파일) |
규칙은 "누가 닿으면 안 되나"가 아니라 "누가 닿아도 되나"를 적는다. 이 성질은 **패키지** 쪽에서만 온다.
패키지는 허용 목록이라, 나중에 새 전송 패키지가 생겨도 따로 고치지 않아도 막힌다. 사용자 전송 **타입**
+3 -2
View File
@@ -17,8 +17,9 @@ use case ── tx.inWrite ─┬─▶ repository.save(aggregate) ┐
DB 저장과 broker 발행을 따로 하면(dual write) 둘 중 하나만 성공하는 순간이 생긴다. outbox는 그 순간을
없앤다. 대가는 **적어도 한 번** 전달이다 — 소비자는 event id로 중복을 걸러야 한다.
정본: `src/application-core/README.md` 「계약 타입」(이벤트 타입 표), `docs/messaging/outbox-inbox.md`,
`docs/messaging/delivery-guarantees.md`.
정본: `src/application-core/README.md` 「계약 타입」(이벤트 타입 표). 메시징 라이브러리 쪽 정본은 그 repo의
[outbox-inbox.md](https://git.learn.hyeonworks.com/donghyeon.kang/messaging-library/src/branch/main/docs/messaging/outbox-inbox.md)와
[delivery-guarantees.md](https://git.learn.hyeonworks.com/donghyeon.kang/messaging-library/src/branch/main/docs/messaging/delivery-guarantees.md)다.
## 순서
-256
View File
@@ -1,256 +0,0 @@
# 설정 레퍼런스
> **Prefix.** Every property below binds under `app.messaging`, which is the prefix the deployed
> runtime and the `APP_MESSAGING_*` environment variables already use. Earlier revisions of this
> page documented a bare `messaging` prefix and the starter bound `backend.messaging`; neither
> bound what this page describes, so a deployment configured from it changed nothing. A key under
> either of the old prefixes now fails startup with a message naming the key — see
> `MessagingPrefixMigrationValidator`.
> **이 페이지는 실행된다.** 아래 YAML 블록은 `MessagingConfigurationBindingTest`가 이 파일에서 직접
> 읽어 컨텍스트에 올린다. 문서가 설명하는 모양이 곧 바인딩되는 모양이라는 뜻이고, 문서를 고치면서
> 코드를 고치지 않으면 테스트가 깨진다. 이전 판은 destination·broker·security 세 섹션을 설명했지만
> 어떤 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 이름으로 추론하지 않는다. 모든 발행(outbox relay 포함)이 이 bridge를 지나므로 messaging
모듈이 켜진 상태에서 값이 없으면 기동이 거부된다.
## Outbox
application의 발행 경로는 하나다(2026-09-28): `outbox_event` 표와 `composition:outbox-relay`. vendored
platform의 `messaging_outbox`(`outbox-inbox.md`)는 이 경로에 쓰이지 않는다 — 두 모델의 상태 대응은
`outbox-inbox.md` 머리의 표에 있다. use case가 `IntegrationEventEncoderPort`로 만든
`ValidatedIntegrationEvent`를 `OutboxAppendPort`로 append하고, relay는 claim한 row의 exact envelope
bytes를 `IntegrationEventPublishPort`로 보낸다. 예전의 `app.outbox.canonical-transport-enabled`
gate와 legacy `MessageBroker → KafkaSender` 경로는 삭제됐다. 발행할 contract의 logical destination마다
아래 destination profile을 선언한다(템플릿의 durable operation event는 `durable-operations`).
## Destination profile
```yaml
app:
messaging:
destinations:
order-events:
broker: kafka-primary
kind: EVENT_STREAM # ASYNC_COMMAND | DOMAIN_EVENT | INTEGRATION_EVENT
# | WORK_QUEUE | PUBLISH_SUBSCRIBE | EVENT_STREAM | REQUEST_REPLY
tier: M1 # M1 | M2 | M3
physical:
topic: order.events.v1
schema:
codec: application/json
compatibility: BACKWARD_TRANSITIVE
message-types: [order.created]
guarantees:
delivery: AT_LEAST_ONCE # AT_MOST_ONCE | AT_LEAST_ONCE
ordering: KEY # NONE | DESTINATION | PARTITION | KEY
external-side-effect: INBOX_TRANSACTIONAL
producer:
confirmation: REPLICATION_OR_PERSISTENCE_ACK
timeout: 5s
mandatory-routing: true
idempotent: true
consumer:
group: order-projection
concurrency: 1 # DESTINATION 순서를 요구하면 1이어야 한다
max-in-flight-per-ordering-unit: 1
prefetch: 16
handler-timeout: 30s
manual-settlement: false
retry:
mode: PAUSE_PARTITION # NONE | INLINE | BLOCKING | PAUSE_PARTITION
# | RETRY_DESTINATION | BROKER_DELAYED
max-attempts: 3
initial-delay: 200ms
max-delay: 2s
multiplier: 2.0
jitter: true
ordering-impact: PRESERVE # PRESERVE | ALLOW_REORDER
dlq:
destination: order-events-dlq
max-redrive-count: 1
payload:
max-bytes: 1048576
claim-check-threshold-bytes: 1048576
key-resolver-configured: true
production: false
topology-auto-create: false
order-events-dlq:
broker: kafka-primary
kind: WORK_QUEUE
guarantees:
delivery: AT_MOST_ONCE # terminal DLQ: another DLQ is not required
physical:
topic: order.events.v1.dlt
schema:
message-types: [order.created]
```
`dlq.destination`이 가리키는 destination도 선언되어야 한다. 선언되지 않은 이름은 부팅 실패이며,
메시지가 갈 곳 없는 DLQ 설정이 조용히 통과하지 않는다. `retry.destination`과 `dlq.destination`이
섞여 만드는 순환(A의 retry가 B로, B의 dlq가 A로)도 하나의 그래프로 검사되어 경로와 함께 거절된다.
## 기본값
| 설정 | 기본값 | 근거 |
|---|---:|---|
| logical payload 최대 | 1,048,576 bytes | portability. 초과는 Claim Check |
| global hard 최대 | 8,388,608 bytes | 어떤 destination도 넘을 수 없는 상한 |
| header 총 크기 | 32,768 bytes | |
| header 개수 | 64 | |
| header key | 128 bytes | metric tag 안전 |
| header value | 4,096 bytes | |
| publish timeout | 5s | |
| handler timeout | 30s | |
| graceful shutdown drain | 30s | |
| 일반 destination retry | 0회 | 자동 retry는 opt-in |
| DLQ redrive batch | 100 | 한 번의 작업이 source를 덮치지 않게 |
| Outbox relay batch | 100 | |
| Outbox lease | 30s | |
| Outbox polling | 500ms | |
| metric dimension 상한 | 200 | cardinality 폭발 방지 |
`schema.codec`은 `application/json`, `schema.compatibility`는 `BACKWARD_TRANSITIVE`,
> **현재 강제 범위:** `schema.compatibility` 값은 현재 정책 선언이며 runtime/CI에서 schema registry를
> 조회해 호환성을 차단하지 않는다. Avro 비교기는 독립 utility/test로만 존재한다. 따라서 이 값을
> 설정했다고 breaking schema가 자동 거부된다고 해석하면 안 된다. 실제 registry gate가 wiring되기
> 전까지 호환성은 adopter의 schema CI가 소유한다.
`guarantees.delivery`는 `AT_LEAST_ONCE`, `retry.mode`는 `NONE`이 기본값이다. 자동 retry가 기본으로
꺼져 있는 이유는 순서를 흐트러뜨리거나 비멱등 side effect를 두 번 실행하는 retry가 눈에 보이는
실패보다 나쁘기 때문이다.
## Broker profile
브로커는 `app.messaging.brokers` 아래에 한 번만 기술한다. `type`은 `kafka`만 받는다 — transport가
있는 계열이 Kafka 하나뿐이다. RabbitMQ 키(`addresses`, `prefetch`, `quorum-queues` 등)와
`type: rabbitmq`는 2026-09-25에 설정 모델에서 삭제됐다. 연결할 transport 없이 바인딩만 되던 키라,
지금은 무시되지 않고 키 이름을 담아 부팅 실패로 거절된다.
### Kafka
```yaml
app:
messaging:
brokers:
kafka-primary:
type: kafka
stable: true
production: false
bootstrap-servers: [broker-1:9093, broker-2:9093]
enable-idempotence: true # stable에서 필수
acks: all # stable에서 필수
max-in-flight-requests-per-connection: 5 # 최대 5
delivery-timeout: 30s
enable-auto-commit: false # 항상 금지
consumer-group: order-projection
tls-enabled: false # production이면 필수
authentication-enabled: false # production이면 필수
```
`production: true`인 Kafka 브로커는 `tls-enabled`와 `authentication-enabled`가 모두 참이어야 하고,
그렇지 않으면 `KafkaProfileValidator`가 부팅을 거절한다. `app.messaging.broker`로 고를 수 있는 값은
`kafka`뿐이다. 위 예시가
`production: false`인 것은 이 페이지가 그대로 실행되는 fixture이기 때문이며, 실 배포는 셋 다 참이다.
Kafka producer는 이 항목 하나로 만든다. `bootstrap-servers`, `acks`, `enable-idempotence`,
`max-in-flight-requests-per-connection`, `delivery-timeout`이 그대로 client 설정이 된다.
`spring.kafka.bootstrap-servers`는 읽지 않는다. type이 `kafka`인 항목이 정확히 하나가 아니면 기동에
실패한다. `send()`가 metadata를 기다리며 호출 스레드를 막는 시간(`max.block.ms`)은 기본 publish
timeout(5s)이다.
## 보안
```yaml
app:
messaging:
security:
kafka-primary:
producer: { type: SASL_SCRAM, credential-id: kafka-producer }
consumer: { type: SASL_SCRAM, credential-id: kafka-consumer }
# admin은 application runtime에 설정하지 않는다
hostname-verification: true
# 사설 CA로 서명된 TLS 브로커면(tls-enabled: true일 때만):
# trust-store: { location: /etc/kafka/ca.p12, type: PKCS12, password-credential-id: kafka-truststore }
access:
publishable: [order-events]
consumable: []
administrable: []
```
키는 `app.messaging.brokers`에 선언된 브로커 이름과 같아야 한다. `tls-enabled`와 `production`은
브로커 쪽에만 있고 여기에 중복되지 않는다 — 하나의 브로커가 두 곳에서 기술되면 두 값이 어긋나는
날이 오고, 어느 쪽이 이기는지는 아무도 모른다.
`credential-id`는 이름일 뿐이고 자격 증명 자체가 아니다. 실제 재료는 `CredentialProvider`가
연결 시점에 해석하므로, 설정 덤프나 힙 덤프에서 나오는 것은 이름뿐이다. producer와 consumer는
서로 다른 `credential-id`를 써야 하며, 같으면 부팅에 실패한다.
`SASL_SCRAM`·`USERNAME_PASSWORD`의 사용자 이름은 `CredentialProvider.username(credentialId)`가
준다. credential id를 사용자 이름으로 보내지 않는다. 비밀번호와 사용자 이름은 JAAS 문자열에 들어가지
않고, 연결이 인증할 때마다 provider에서 읽힌다. 그래서 provider가 만료 시각을 주는 credential은
재기동 없이 rotation된다(`security.md`).
`MUTUAL_TLS`는 클라이언트 인증서를 key store로 제출한다. `credential-id`는 key store 비밀번호를
가리킨다.
```text
producer:
type: MUTUAL_TLS
credential-id: kafka-producer-tls # key store 비밀번호
key-store: { location: /etc/kafka/producer.p12, type: PKCS12 }
```
`trust-store`를 생략하면 JVM 기본 trust store를 쓴다. 사설 CA 브로커는 `trust-store.location`
(PKCS12·JKS·PEM)과, 잠긴 store면 `password-credential-id`를 준다.
Kafka producer는 이 항목을 실제 클라이언트 설정(`security.protocol`, `sasl.mechanism`,
`sasl.jaas.config`, `sasl.client.callback.handler.class`, `ssl.truststore.*`, `ssl.keystore.*`,
`ssl.enabled.protocols=TLSv1.3,TLSv1.2`, hostname 검증)으로 옮긴다. 평문으로 조용히 넘어가지
않도록 다음 경우 부팅에 실패한다: 브로커가 `tls-enabled`나 `authentication-enabled`를 켰는데
`app.messaging.security.<broker>`가 없을 때, security 항목은 있는데 `CredentialProvider` bean이 없을
때, 같은 브로커에 맞는 항목이 둘 이상일 때, provider가 SASL 사용자 이름을 주지 않을 때,
`MUTUAL_TLS`인데 `key-store`가 없거나 `tls-enabled`가 꺼져 있을 때, `trust-store`를 줬는데
`tls-enabled`가 꺼져 있을 때, store 파일을 열 수 없을 때.
`access.publishable`은 강제된다. security 항목이 있는 브로커의 destination은 이 목록에 있어야
publish된다. 목록 밖 publish는 `REJECTED`(`PUBLISH_FORBIDDEN`)이고, 빈 목록이면 아무것도 publish되지
않는다.
## Backpressure
```yaml
app:
messaging:
backpressure:
global-limit: 512
per-destination-limit: 64 # global-limit 이하여야 한다
```
`per-destination-limit > global-limit`이면 global limit이 limit이 아니게 되므로 부팅에 실패한다.
## 바인딩되지 않는 키
섹션은 바인딩되는데 그 안의 키 하나가 오타인 경우는 접두사 오타와 달리 조용하다 — 섹션은 붙고,
플랫폼은 뜨고, 바꾸러 온 그 설정만 적용되지 않는다. `MessagingConfigurationKeyValidator`가
`app.messaging.destinations|brokers|security` 아래의 모든 키를 settings 레코드에서 파생한 목록과
대조하고, 없는 키는 그 키 이름을 담아 부팅을 거절한다.
허용 키 목록은 이 문서가 아니라 레코드에서 나온다. 문서에 목록을 적으면 필드가 추가된 날 그
목록이 틀리고, 오타를 잡으라고 만든 검사가 정상 필드를 거절하게 된다.
환경변수(`APP_MESSAGING_...`)는 이 검사의 대상이 아니다. `APP_MESSAGING_DESTINATIONS_ORDER_EVENTS_
CONSUMER_PREFETCH`에서 entry 이름과 leaf를 가르는 밑줄은 둘 안에 있는 밑줄과 구별되지 않으므로,
되돌려 쪼개려면 추측해야 한다. 여기서의 추측은 정상 배포를 거절하는 쪽으로 틀리며, 그것은 배포
매니페스트에 손으로 적어야 하는 변수에서 오타 하나를 놓치는 것보다 나쁘다.
-35
View File
@@ -1,35 +0,0 @@
# 기존 runtime → 신규 messaging platform cutover (MSG-015)
## 왜 기계적 매핑이 안 되는가
두 outbox 모델의 enum 이름이 겹치는데 의미가 반대다.
| 모델 | retryable | terminal |
|---|---|---|
| 기존 `OutboxEventStatus` | `FAILED` (`next_attempt_at` 보유) | `DEAD` |
| 신규 `OutboxStatus` | `AMBIGUOUS` | `FAILED`, `EXHAUSTED` |
이름으로 매핑하면 **확정 거절이 무한 재시도**가 되고 **불확정이 park**된다. 그래서 application은
자기 어휘(`OutboxPublishOutcome`)만 쓰고, 변환은 bridge adapter가 한다.
## 지금 반영된 것
- `OutboxPublishOutcome` — `CONFIRMED` / `AMBIGUOUS` / `REJECTED_BEFORE_SEND` /
`REJECTED_AFTER_BROKER`. application이 소유하는 canonical 결과 타입이며, "리턴 or throw"만 가능한
기존 어댑터를 위해 `OutboxMessagePublishPort.publishForOutcome`의 default가 `CONFIRMED`를 돌려준다.
- `APPLICATION_DOES_NOT_DEPEND_ON_THE_MESSAGING_PLATFORM` ArchUnit 규칙 — application-core가
`dev.caskeleton.messaging..`를 import하면 빌드가 깨진다.
- 반대 방향(신규 `PublishResult` → application outcome) 매핑 규칙을 테스트로 고정.
## 남은 것
- `messaging-platform-bridge` outbound leaf: validated application event → platform envelope,
`PublishResult` → `OutboxPublishOutcome`. registry에 leaf를 추가하는 변경이라 별도 커밋.
- golden contract 테스트: event/message ID, type, schema revision, partition/order/correlation/
causation/tenant/trace, payload digest, wire version이 bytes 단위로 보존되는지.
- 단일 publication authority: writer/relay가 동시에 ACTIVE가 되지 않도록 하는 fence. 이 용도로 쓰려던
outbox V2의 `OutboxPublicationAuthority`는 한 번도 조립되지 않은 채 2026-09-25에 삭제됐으므로
(`docs/capability-status.md` "제거된 코드") cutover가 자기 fence를 새로 가져야 한다. **dual write/publish는 금지** — 한 business fact가 두 durable store와
두 relay로 나가는 상태가 cutover에서 가장 위험하다.
- 첫 cutover 범위는 **transport만** 교체(저장소는 기존 유지). storage migration은 shadow read →
authority switch → old backlog drain 순서로 별도 release.
-80
View File
@@ -1,80 +0,0 @@
# 전달 보장
## 왜 `EXACTLY_ONCE`가 없는가
어떤 브로커도 **외부 side effect를 포함한** exactly-once를 제공하지 않는다.
실제로 존재하는 것은 at-least-once 전달 + 멱등하거나 transactional한 consumer의 조합이다.
플랫폼이 지킬 수 없는 이름을 enum에 두면 그 책임이 눈에 보이지 않는 곳으로 밀려난다.
그래서 `DeliveryGuarantee`는 증거가 끝나는 지점에서 멈춘다.
```java
public enum DeliveryGuarantee { AT_MOST_ONCE, AT_LEAST_ONCE }
```
## Publish 결과는 boolean이 아니다
```java
public enum PublishCompletion { CONFIRMED, REJECTED, AMBIGUOUS }
```
`REJECTED`와 `AMBIGUOUS`를 하나의 "실패"로 합치면 중복 주문이 만들어진다.
전자는 broker가 저장하지 않았음이 **확정**되어 중복 걱정 없이 다시 보내거나 포기할 수 있고, 후자는 그렇지 않다.
`REJECTED`가 곧 "포기해도 된다"는 뜻은 아니다. 거부 이유가 그 순간에 속하면(종료 중
`SHUTTING_DOWN`, permit 대기 초과, `PUBLISH_RUNTIME_UNAVAILABLE`, `KAFKA_TRANSPORT_CLOSED`, Kafka
인증·인가 실패) `failure().retryable()`이 true이고, 호출자는 같은 메시지를 나중에 다시 보내야 한다.
포기해도 되는 것은 `retryable=false`인 거부뿐이다.
| 상황 | 결과 |
|---|---|
| 로컬 validation 실패 | `REJECTED`, `NOT_TRANSMITTED` |
| broker 명시적 reject / nack | `REJECTED` |
| confirm 수신 | `CONFIRMED` |
| Rabbit confirm + unroutable return | `REJECTED`, `UNROUTABLE` |
| bytes 전송 후 connection loss | `AMBIGUOUS` |
| confirm timeout | `AMBIGUOUS` |
| adapter가 판정 불가 | 보수적으로 `AMBIGUOUS` |
`PublishResult` 생성자가 이 규칙을 강제한다. `CONFIRMED`인데 broker acceptance가 없거나,
`AMBIGUOUS`인데 confirmation level을 주장하면 **객체 생성 자체가 실패**한다.
## Ordering
```java
public enum OrderingScope { NONE, DESTINATION, PARTITION, KEY }
```
순서는 partition·key·단일 consumer의 성질이지 destination 전체의 성질이 아니다.
`GLOBAL`이 없는 이유가 이것이다.
`DestinationProfileValidator`가 다음을 거부한다.
- `ordering=KEY`인데 key resolver 없음
- ordered destination인데 `ALLOW_REORDER` retry
- `orderingImpact=PRESERVE`인데 재발행형 retry(`RETRY_DESTINATION`, `BROKER_DELAYED`)
- `ordering=DESTINATION`인데 concurrency > 1
- ordered destination인데 ordering unit당 in-flight > 1
## External side effect
```java
public enum ExternalSideEffectGuarantee { NONE, IDEMPOTENCY_REQUIRED, INBOX_TRANSACTIONAL }
```
`INBOX_TRANSACTIONAL`만이 "DB side effect와 중복 차단이 같은 transaction에서 commit된다"를 의미한다.
Kafka transaction은 **Kafka 안에서만** 원자적이므로 이 값과 함께 설정하면
`KafkaTransactionProfileValidator`가 거부한다. 두 개의 독립적인 commit을 하나로 착각하게 두지 않기 위해서다.
## Consumer settlement 순서
```text
RECEIVED → DECODING → PROCESSING → HANDLER_SUCCEEDED → SETTLEMENT_SENDING
├→ SETTLED
└→ SETTLEMENT_UNKNOWN
```
- handler는 broker ACK API를 호출하지 않는다.
- `Success` 이후에만 source settlement한다.
- `SETTLEMENT_UNKNOWN`은 성공이 아니다. redelivery 가능성을 의미한다.
- `SettlementResult` 생성자가 `SETTLED`인데 `redeliveryPossible=true`인 조합을 거부한다.
-58
View File
@@ -1,58 +0,0 @@
# Experimental 정책
## Stable과 Experimental의 차이
**Stable**은 공통 Contract Suite(`MessagingAdapterContract`)를 변경 없이 통과한 어댑터다.
컴파일되는 어댑터가 아니라, 아래 7가지를 실제로 증명한 어댑터다.
```text
publishesAndConfirms
returnsAmbiguousWhenConfirmIsLost
redeliversWhenSettlementIsLost
preservesMessageIdAcrossRetryAndDlq
keepsSourceUnsettledWhenDlqPublishFails
rejectsOversizedPayloadBeforeTransport
stopsAcceptingNewWorkDuringShutdown
```
**Experimental**은 아직 그 증명이 끝나지 않은 어댑터다.
현재 Experimental 어댑터는 없다. Kafka Share Group·Pulsar·NATS JetStream(Experimental), RabbitMQ,
Spring Cloud Stream bridge(Optional)는 SDK 없는 seam이거나 선택할 수 없는 상태여서 2026-09-25에
삭제했다(`docs/capability-status.md` 제거 표). 이 문서는 새 어댑터를 들일 때 지킬 규칙이다.
## 규칙
### 1. 기본 비활성
새 Experimental 어댑터는 자기 활성화 플래그를 가지고 기본값은 `false`다.
활성화하지 않으면 validator가 `MessagingCapabilityUnavailableException`을 던진다.
Contract Suite가 아직 증명 중인 어댑터가 누군가의 기본 설정 때문에 load-bearing이 되어서는 안 된다.
### 2. Stable 모듈이 Experimental 모듈에 의존하지 않는다
Gradle 의존 그래프로 강제된다. Experimental leaf는 `messaging-spring-boot-starter`의
`allowed_dependencies`에 넣지 않는다.
`verifyCleanArchitectureDependencies`가 위반을 빌드 실패로 만든다.
### 3. Core 계약을 바꾸지 않는다
Experimental 어댑터는 브로커의 차이를 `MessagingCapabilities`로 표현할 뿐,
`messaging-core-api`의 타입을 바꾸지 않는다.
### 4. 없는 기능을 광고하지 않는다
Contract Suite로 증명하지 않은 capability는 `MessagingCapabilities`에서 `false`로 둔다.
`false`인 capability를 요구하는 profile은 startup에서 실패한다. 조용히 약화되지 않는다.
## 승격 조건
Experimental → Stable로 올리려면 전부 필요하다.
1. `MessagingAdapterContract` 7개 테스트를 변경 없이 통과
2. 장애 주입(연결 끊김, confirm 유실, settlement 유실) 하에서 통과
3. 지원 브로커 버전 범위 명시 및 CI 검증
4. `support-matrix.md`의 capability 표 갱신
5. ADR 작성
6. 기본 활성화 여부에 대한 별도 결정
-126
View File
@@ -1,126 +0,0 @@
# 마이그레이션 가이드
## 기존 Spring Kafka / Spring AMQP 코드에서
### 1. topic 이름을 코드에서 제거한다
```java
// before
kafkaTemplate.send("order.events.v1", key, payload);
// after
publisher.publish(orderEvents, envelope, PublishOptions.defaults());
```
`MessageDestination`은 logical name만 가진다. 물리 매핑은 destination profile이 소유한다.
`DestinationName`의 패턴이 `topic://orders` 같은 값을 거부하므로 우회할 수 없다.
### 2. boolean 성공 판정을 없앤다
```java
// before
try { template.send(...).get(); success(); }
catch (Exception e) { fail(); } // REJECTED와 AMBIGUOUS를 구분하지 못한다
// after
PublishResult result = ...;
switch (result.completion()) {
case CONFIRMED -> success();
case REJECTED -> abandon(); // broker가 저장하지 않음이 확정
case AMBIGUOUS -> retrySameMessageId(result); // broker가 가지고 있을 수 있음
}
```
이 구분이 없으면 confirm 유실 한 번이 중복 주문 하나가 된다.
### 3. auto-commit / auto-ack를 끈다
```yaml
# Kafka
enable.auto.commit: false
# RabbitMQ
auto-ack: false
```
둘 다 validator가 강제로 거부한다. 타이머 기반 commit은 handler가 실행되기도 전에
메시지를 처리 완료로 표시한다.
### 4. handler에서 ack 호출을 제거한다
```java
// before
@KafkaListener(...)
void handle(ConsumerRecord<?,?> record, Acknowledgment ack) {
process(record);
ack.acknowledge(); // 실패 시 순서가 애매해진다
}
// after
CompletionStage<HandleResult> handle(MessageDelivery<OrderCreated> delivery) {
process(delivery.message().payload());
return completedFuture(HandleResult.success());
}
```
settlement는 플랫폼이 수행한다. "성공한 뒤에만 ack"가 각 handler의 기억이 아니라
플랫폼 불변식이 된다.
### 5. 중복을 정상 상황으로 다룬다
at-least-once는 중복을 전제한다. 세 가지 중 하나를 고른다.
| 방식 | 언제 |
|---|---|
| handler 자체 멱등 | 자연 멱등 연산 (upsert 등) |
| Inbox | DB side effect가 있는 경우 |
| Kafka transaction | Kafka → Kafka 파이프라인만 |
`ExternalSideEffectGuarantee`에 선언한다. `INBOX_TRANSACTIONAL`과 Kafka transaction을
동시에 설정하면 거부된다. Kafka transaction은 DB를 포함하지 않는다.
### 6. 큰 payload는 Claim Check로
broker frame 크기를 키우지 않는다. broker 메모리, replication latency,
consumer recovery가 동시에 나빠지고, 유계·검증 가능한 실패가 무계 실패로 바뀐다.
1 MiB 초과는 외부 저장소로 offload하고 digest를 포함한 참조만 발행한다.
## DB 마이그레이션
```text
V1001__messaging_outbox.sql
V1002__messaging_outbox_lease_fencing.sql
V1003__messaging_admin_operation_journal.sql
V1004__messaging_outbox_canonical_metadata.sql
V1101__messaging_inbox.sql
```
Messaging owns Flyway versions `1000..1999`. The starter assembles both JDBC reliability modules,
so their migrations deliberately share `classpath:db/migration/messaging` but must never reuse a
version. Keeping them in this reserved range also prevents collisions with the application's
ordinary `db/migration/postgresql` stream, whose low-numbered versions are independent.
When adopting outbox/inbox persistence, add `classpath:db/migration/messaging` to the deployment's
Flyway locations together with its normal application migration location. Do not copy or renumber
these files into the application's low-numbered stream; the reserved range is the namespace
boundary.
Outbox row는 business transaction과 같은 transaction에서 쓴다.
Inbox reservation은 handler side effect와 같은 transaction에서 쓴다.
별도 transaction이면 각 패턴이 닫으려던 창이 그대로 열려 있다.
## 단계적 전환
1. **publish만 전환** — 기존 consumer는 그대로. wire format은 reserved header가 추가될 뿐이다.
2. **Outbox 도입** — publish 유실 창을 닫는다.
3. **consume 전환** — handler를 `MessageHandler`로 옮기고 ack 호출을 제거한다.
4. **Inbox 도입** — 중복 side effect를 닫는다.
5. **retry·DLQ 정책 선언** — 이 시점까지 자동 retry는 0회다.
각 단계는 독립적으로 배포 가능하고, 되돌릴 수 있다.
## 되돌릴 수 없는 것
- 한 번 발행된 message type의 wire contract
- 이미 retention 안에 있는 메시지의 schema
- redrive된 메시지의 `messageId` (바뀌지 않는다 — 이것이 의도다)
-112
View File
@@ -1,112 +0,0 @@
# 운영 Runbook
## 배포 전 체크
```bash
./gradlew architectureCheck --console=plain
./gradlew checkstyleMain --console=plain
```
destination profile은 startup에서 검증된다. 아래는 **부팅 실패**다.
- ordered destination + reorder 가능 retry
- `ordering=KEY` + key resolver 없음
- payload 상한 > 8,388,608 bytes
- DLQ 자기 참조 / retry 자기 참조
- retry·DLQ 그래프 cycle
- 미등록 retry·DLQ destination
- M1 destination + manual settlement
- `AT_LEAST_ONCE` + confirmation `NONE`
- production profile + topology auto-create
- broker topology가 manifest와 불일치
## 증상별 대응
### publish가 AMBIGUOUS로 쏟아진다
broker confirm 경로 문제다. 실패가 아니다.
1. `PublishEvidence.transmission`이 `MAY_HAVE_BEEN_TRANSMITTED`인지 확인
2. Kafka: `delivery.timeout.ms`, ISR 상태, leader election 확인
3. Rabbit: confirm timeout, channel 상태 확인
4. Outbox를 쓰고 있다면 `status='AMBIGUOUS'` row가 같은 messageId로 재시도 중이다. **정상이다.**
5. consumer 쪽 Inbox가 중복을 흡수하는지 확인
`AMBIGUOUS`를 실패로 취급해 새 messageId로 재발행하지 말 것. 중복이 복구 불가능해진다.
### DLQ가 비어 있는데 메시지가 사라졌다
DLQ publish 실패 시 source는 settlement되지 않는다. 메시지는 source에 남아 재전달된다.
1. `msg.failure-code`가 `DEAD_LETTER_*`인 로그 확인
2. DLQ destination이 실제로 존재하는지 (topology validation)
3. DLQ credential에 publish 권한이 있는지
### consumer lag이 한 partition에서만 증가한다
`ContiguousPartitionOffsetTracker`가 gap에서 멈춘 것이다. 설계된 동작이다.
commit은 **연속** 완료 offset까지만 전진한다. offset 11이 아직 실행 중이면
10과 12가 끝나도 watermark는 10에 머문다. 12를 commit하면 consumer가 죽었을 때 11을 잃는다.
1. 해당 partition의 in-flight를 확인
2. 느린 handler를 찾는다 (`handlerTimeout` 초과 여부)
3. 필요하면 `PAUSE_PARTITION` retry가 걸려 있는지 확인
### 재시도 폭풍
`RetryPolicy.jitter=false`인지 확인한다. jitter 없이는 같은 초에 실패한 모든 consumer가
같은 초에 재시도한다.
### shutdown이 오래 걸린다
`GracefulShutdownCoordinator`가 in-flight를 기다리는 중이다.
- `inFlight()`가 0이 되면 즉시 종료
- drain deadline(기본 30초) 초과 시 남은 작업을 **unsettled로 포기**한다 → broker가 재전달
- draining 시작 후 새 retry attempt는 만들지 않는다
## Destructive 작업
전부 `DestructiveOperationGuard`를 통과해야 한다.
| 조건 | 요구 |
|---|---|
| admin credential | application runtime은 보유하지 않음 |
| `AdminApproval` | 유효기간 내 |
| dry-run | 항상 허용 |
### Replay
```text
기본: 격리된 consumer group (replay-<requestId>)
기존 group 대상: 승인 티켓 필수
```
기존 production group으로 replay하는 것은 "다시 읽기"가 아니라 **live consumer를 되감는 것**이다.
그 사이의 모든 것이 재처리된다.
### Redrive
```text
dry-run으로 후보 수 확인
→ 승인 획득
→ batch 100건 이하로 실행
→ republish CONFIRMED 인 것만 DLQ에서 settlement
```
`redriveId`로 재구동 루프를 추적한다. 같은 메시지가 반복해서 redrive되면
근본 원인이 해결되지 않은 것이다.
### Offset reset
`KafkaOffsetResetExecutor`는 승인 predicate를 **생성자 인자**로 받는다.
승인 소스 없이 조립된 runtime은 물리적으로 reset을 수행할 수 없다.
## Topology
production topology는 IaC가 만들고 애플리케이션은 **검증만** 한다.
`TopologyValidationRuntime`은 모든 불일치를 한 번에 보고하고 startup을 실패시킨다.
partition 수가 다르면 destination이 광고하는 ordering 보장이 달라지고,
`min.insync.replicas`가 없으면 `acks=all`의 의미가 달라진다.
-192
View File
@@ -1,192 +0,0 @@
# Outbox · Inbox
> **이 문서의 Outbox는 vendored messaging platform의 outbox다**(`messaging_outbox` 표,
> `messaging-reliability`의 `OutboxRelay`). 이 템플릿 application이 쓰는 outbox는 그것이 아니다.
> application은 `outbox_event` 표(`adapter:outbound:persistence-jpa`)에 append하고, relay는
> `composition:outbox-relay`가 돌린다. 그 동작과 운영은 `docs/manual/09-outbox-events.md`,
> `src/composition/outbox-relay/README.md`, `docs/runbooks/outbox-dead-letter.md`,
> `docs/runbooks/outbox-publish-failed.md`에 있다. platform outbox는 소유자 결정으로 제품 안에 남아
> 있지만, platform outbox repository bean이 없으면 그 relay는 만들어지지 않는다(리뷰 2026-11-01 06-11).
>
> 두 모델은 같은 이름의 상태가 반대 뜻이다. 이름으로 옮기면 확정 거부는 영원히 재시도되고 응답 없는
> 메시지는 버려진다. 대응은 아래 표 하나로만 읽는다(`OutboxPublishOutcome` Javadoc과 같은 내용).
>
> | 일어난 일 | application `outbox_event` | platform `messaging_outbox` |
> |---|---|---|
> | broker가 확인했다 | `PUBLISHED` | `PUBLISHED` |
> | 응답이 없었다(저장됐을 수 있음) | `FAILED`(재시도, 예산 안 씀, 끝 없음) | `AMBIGUOUS`(재시도, 예산을 다 쓰면 `EXHAUSTED`) |
> | 지금만 거부됐다(종료·포화·credential) | `FAILED`(재시도, 예산 안 씀, 끝 없음) | `FAILED`(종단) |
> | 확정 거부됐다(같은 payload는 또 거부) | `DEAD`(종단, 수동 처분) | `FAILED`(종단) |
> | publisher가 예외를 던졌고 시도 예산을 다 썼다 | `DEAD`(종단, 수동 처분) | `EXHAUSTED`(종단) |
> | 운영자가 재시도를 멈췄다 | `PARKED`(수동 재개·skip) | 없음 |
>
> **이 템플릿 application의 소비 경로**: application의 `MessageHandler`와 inbox 부품(애플리케이션
> DataSource 위 `JdbcInboxRepository`, `PlatformTransactionManager` 위 `TransactionRunner`)은
> `adapter:inbound:messaging`(`src/adapter/inbound/messaging/README.md`)이 둔다. platform starter는 두
> bean이 있을 때 `IdempotentConsumer`를 만들어 `INBOX_TRANSACTIONAL` destination의 handler를 감싼다.
> 그 leaf는 inbox 마이그레이션(`V1101`)만 자기 history 표로 적용하므로, 아래 "location 추가"는 platform
> outbox를 쓰는 배포의 이야기다. payload decode 목록은 handler bean의 선언으로 만든다.
## 두 패턴이 각각 무엇을 해결하는가
| 패턴 | 해결하는 문제 | 해결하지 않는 문제 |
|---|---|---|
| Transactional Outbox | DB commit과 publish 사이의 창(窓) | 중복 |
| Inbox | 중복 delivery의 side effect | 유실 |
**둘 다 필요하다.** Outbox만으로는 exactly-once가 되지 않는다.
## 채택할 때 먼저 적용할 DB migration
Outbox/Inbox JDBC 모듈의 DDL은 `classpath:db/migration/messaging`에 있다. Messaging은
Flyway version `1000..1999`를 예약해서 애플리케이션의 일반적인 저번호 migration과 버전이
겹치지 않게 한다.
배포에서 이 JDBC 구현을 채택할 때는 기존 Flyway location에 다음 location을 **추가**한다.
```text
classpath:db/migration/messaging
```
현재 순서는 `V1001..V1005`(outbox/admin)와 `V1101`(inbox)이고, 모두
`messaging-reliability-jdbc-postgresql`에 있다. starter 테스트가 그 모듈을 실제 combined classpath로 올려 version 중복과 예약 대역 이탈을 검사한다. 개별 DDL의
의미와 전환 순서는 [migration-guide.md](migration-guide.md)를 따른다.
## Outbox
business transaction과 **같은 transaction**에서 row를 쓴다. 둘 다 commit되거나 둘 다 안 된다.
```sql
BEGIN;
UPDATE orders SET status = 'PLACED' WHERE id = ?;
INSERT INTO messaging_outbox (message_id, destination, ...) VALUES (?, ?, ...);
COMMIT;
```
### relay
```text
claimBatch(owner, 100, 30s, now, maxAttempts) -- owner + fencing token으로 다중 relay 인스턴스 안전
→ publish (messageId 그대로)
→ CONFIRMED → markPublished
→ AMBIGUOUS → markAmbiguous (같은 messageId로 재시도 가능)
→ REJECTED → markFailed
```
row 하나의 실패는 그 row에서 끝난다. envelope로 만들 수 없는 row(예약 header `msg.*`를 담은 row
등)는 `FAILED`가 되고, publisher가 예외를 던지면 결과를 모르므로 `AMBIGUOUS`가 된다. 같은 batch의
나머지 row는 그대로 publish된다. pass 전체가 실패하면(DB 연결 등) WARN 로그를 남기고
`messaging.outbox.relay.failed.passes` 카운터를 올린다.
### 핵심 규칙: ambiguous는 같은 messageId로 재시도
새 id를 발급하면 "전달됐을 수도 있는 메시지"가 "확실히 두 번째인 메시지"가 되어
downstream의 어떤 중복 제거도 복구할 수 없다.
failed로 표시하면 broker가 이미 가지고 있을 수 있는 메시지를 잃는다.
`message_id`를 primary key로 둔 것도 같은 이유다. 어떤 코드 경로도 실수로 새 id를 붙일 수 없다.
### lease
```text
status IN ('PENDING','AMBIGUOUS','IN_FLIGHT')
AND (lease_expires_at IS NULL OR lease_expires_at <= now)
AND next_attempt_at <= now
AND attempts < maxAttempts
AND (ordering_key IS NULL
OR 같은 destination·ordering_key의 더 오래된 미완료 row가 없음)
```
`ordering_key`가 있는 row는 같은 key의 더 오래된 row가 `PENDING`·`AMBIGUOUS`·`IN_FLIGHT`인 동안
claim되지 않는다. 이 조건이 없으면 두 relay가 같은 key의 두 row를 나눠 가져가거나, AMBIGUOUS로
재시도되는 row보다 뒤의 row가 먼저 나간다(`OutboxPostgresIT#aNewerRowWaitsWhileAnOlderRowWithTheSameOrderingKeyIsUnfinished`).
`V1005`의 partial index가 이 확인을 받친다. 더 오래된 row가 `FAILED`·`EXHAUSTED`가 되면 뒤의 row는
진행한다.
`IN_FLIGHT`가 목록에 있는 것이 핵심이다. relay가 publish 도중 죽으면 row는 `IN_FLIGHT`로 남는데,
이를 제외하면 그 메시지는 **영원히** 발행되지 않는다 — outbox가 막으려던 바로 그 실패다. 대신
lease가 만료됐을 때만 회수하므로, 살아 있는 relay가 들고 있는 row는 회수되지 않는다.
회수는 **같은 `message_id`로** 이루어지고 `lease_token`이 1 증가한다. 새 id를 발급하면 "전달됐을
수도 있는 메시지"가 "확실히 두 번째"가 되기 때문이다 (위의 AMBIGUOUS 논의와 같은 이유).
이 문단의 근거는 실제 PostgreSQL 컨테이너 레인이다:
- `OutboxPostgresIT#anExpiredLeaseBecomesClaimableAgain` — 만료된 lease의 재회수
- `OutboxPostgresIT#anExpiryReclaimKeepsTheMessageIdAndAdvancesTheToken` — 같은 id, 증가한 token
- `OutboxPostgresIT#aLeasedRowIsInvisibleToASecondRelayInstance` — 살아 있는 lease는 회수 불가
- `OutboxPostgresIT#aSupersededRelayCannotOverwriteTheOutcomeOfTheOneThatReplacedIt` — fencing
partial index `ix_messaging_outbox_claimable`이 이 쿼리를 backlog 크기에 비례하게 유지한다.
PUBLISHED row는 retention job이 지울 때까지 쌓이기 때문이다.
## Inbox
reservation과 side effect가 **같은 transaction**이어야 한다.
```java
transactions.inTransaction(() -> {
if (!inbox.reserve(messageId, consumerId, now)) {
return InboxOutcome.duplicate(); // 이미 처리됨
}
return InboxOutcome.processed(sideEffect.get());
});
```
별도 transaction으로 예약하면 Inbox가 닫으려던 바로 그 창이 다시 열린다.
### 소비와 연결 (소유자 결정 10)
consume 계약은 `MessageHandler<T>` 하나다. handler를 bean으로 등록하면 `messaging-spring-boot-starter-kafka`가
그 handler가 가리키는 destination마다 Kafka consumer를 연다(`app.messaging.enabled=false`면 없다).
- destination profile이 `guarantees.external-side-effect: INBOX_TRANSACTIONAL`이면 platform이 handler를
`InboxMessageHandler`로 감싼다. 예약과 handler의 쓰기가 같은 transaction에서 commit되고, 이미 예약된
message는 handler를 부르지 않고 `Success`로 settle한다. 이 경우 애플리케이션이 `IdempotentConsumer`
bean(inbox repository + transaction runner)을 둬야 하며, 없으면 기동이 실패한다.
- inbox의 consumer 식별자와 Kafka `group.id`는 destination의 `consumer.group`이다. 없으면 기동이 실패한다.
- offset은 handler가 `Success`로 답하고 (inbox destination이면) 그 transaction이 commit된 뒤에만, 또는
DLQ 토픽 기록이 확인된 뒤에만 넘어간다. auto-commit은 쓰지 않는다.
- `Retry`·예외·timeout은 `retry.max-attempts`까지 partition을 멈추고 다시 읽으며, 다 쓰면 DLQ 토픽에
원본 record를 남기고 넘어간다. DLQ가 없는 destination(at-most-once)은 넘어가지 않고 멈춘다.
- `Reject`는 at-most-once destination에서만 버리고, 그 밖에서는 dead letter로 보낸다.
실제 왕복·중복 제거·DLQ는 `MessagingKafkaConsumeQualificationTest`(Kafka + PostgreSQL Testcontainers)가 확인한다.
애플리케이션 경로(앱 outbox relay가 발행 → `adapter:inbound:messaging`이 조립한 inbox와 JPA 트랜잭션 →
handler)의 중복 전달·실패 재처리는 `InboxRedeliveryIntegrationTest`(lane
`messagingInboxRedeliveryIntegrationTest`)가 확인한다. 애플리케이션 handler가 쓰기 use case를 부르는 방법
(`@SystemCaller` handler가 `@SystemInvoked` use case를 직접 만든다)은 `docs/manual/09-outbox-events.md`
「소비」 4단계다.
### 복합 키
`PRIMARY KEY (message_id, consumer_id)`.
message_id만으로 중복 제거하면 같은 event를 소비하는 두 번째 consumer가
첫 번째에 의해 억제된다. 각 consumer가 한 번씩 처리해야 한다.
### retention
broker의 최대 redelivery window보다 **길어야** 한다.
row를 먼저 지우면 늦게 도착한 redelivery가 두 번 처리된다.
outbox·inbox cleanup job은 한 번에 최대 1,000행씩 지우고, 지운 수가 1,000보다 적으면 멈춘다.
repository port에는 개수 제한 없는 삭제 메서드가 없다.
## CDC 대안
relay는 polling 하나뿐이다. Debezium Event Router 매핑(`DebeziumOutboxEventRouter` 등)은 조립하는
곳이 없어 2026-09-25에 삭제했다(`docs/capability-status.md` 제거 표). `messaging_outbox`의
`routing_key` 컬럼은 남아 있으므로 CDC를 다시 들일 때 그 컬럼을 message key로 쓴다.
## Claim Check
1 MiB 초과 payload는 broker 프레임을 키우지 않고 외부 저장소로 offload한다.
`ClaimCheckReference`는 digest를 **필수**로 가진다. claim check는 메시지를 서로 다른 retention과
replication을 가진 두 시스템으로 쪼개므로, consumer는 producer가 저장한 바로 그 bytes를 받았음을
증명할 수 있어야 한다. 그렇지 않으면 잘린 객체와 정상 객체를 구분할 수 없다.
`ClaimCheckIntegrityGuard`는 fetch 전에 만료를, fetch 후에 크기와 digest를 검사한다.
digest 불일치는 `DESERIALIZATION`이 아니라 **validation** 실패로 분류한다.
bytes가 깨진 JSON인 게 아니라, 틀린 bytes이기 때문이다.
-112
View File
@@ -1,112 +0,0 @@
# Retry · DLQ · Redrive
## 자동 retry는 opt-in이다
일반 destination의 기본값은 **retry 없음**이다. 순서를 깨거나, 멱등하지 않은 side effect를
증폭시키거나, 이미 throttle된 downstream을 더 때리는 retry는 보이는 실패보다 나쁘다.
## 결정 순서
`DefaultRetryDecisionEngine`은 아래 순서를 위에서 아래로 평가한다.
```text
1. non-retryable category → parking(DeadLetter) 또는 Reject
2. attempt >= maxAttempts → DeadLetter
3. PRESERVE + ordered + orderedStream capability → PauseAndRetry
4. mode=PAUSE_PARTITION → PauseAndRetry
5. mode=RETRY_DESTINATION + ALLOW_REORDER → PublishToRetryDestination
6. mode=INLINE|BLOCKING → RetryInline
7. mode=BROKER_DELAYED + delayedDelivery capability → PublishToRetryDestination
8. 그 외 → DeadLetter
```
**retryability를 attempt 예산보다 먼저** 검사한다. deserialization 실패는 payload가 바뀌지 않으므로
재시도가 3번 더 실패할 뿐이다. 첫 delivery에서 바로 park한다.
**순서 보존 전략을 재발행 전략보다 먼저** 검사한다. 둘 다 설정되어 있어도 ordered destination이
reorder 경로로 흘러내리지 않는다.
## 기본 non-retryable
`DESERIALIZATION`, `AUTHENTICATION`, `AUTHORIZATION`, `CONFIGURATION`은 자동 retry하지 않는다.
매 redelivery마다 동일하게 실패하므로 부하만 늘어난다.
destination profile의 `retryableCategories`로 명시적으로 뒤집을 수는 있다.
## Backoff
`min(maxDelay, initialDelay * multiplier^(attempt-1))`, 이후 full jitter.
full jitter는 `[0, delay]` 균등 분포다. jitter가 없으면 같은 초에 실패한 모든 consumer가
같은 초에 재시도하고, downstream의 회복이 재시도 폭풍으로 즉시 무효화된다.
## Kafka: pause-and-seek vs retry topic
| 전략 | 순서 | 언제 |
|---|---|---|
| `PAUSE_PARTITION` | 유지 | ordered destination |
| `RETRY_DESTINATION` | 깨짐 | work queue, `ALLOW_REORDER` 명시 |
pause-and-seek는 메시지가 로그의 자기 자리를 떠나지 않는다. partition을 멈추고, 기다리고,
같은 offset으로 seek해 재전달한다. 뒤의 메시지도 함께 기다리며 이것이 의도된 동작이다.
`KafkaConsumerRegistrar`가 handler 실패(예외, settle 없이 끝남, timeout)를 다루는 방식:
- 재전달은 destination `retry`의 backoff 뒤에 한다. 최소 1초. 0초 재시도는 없다.
- 같은 offset의 실패 횟수가 `retry.maxAttempts`에 닿으면 `KafkaQuarantinePublisher`에 쓰고,
쓰기가 확인되면 offset을 넘긴다. quarantine이 없으면 backoff로 계속 재시도한다(메시지를 버리지
않는다). 그래서 `production` destination은 quarantine 없이 만들 수 없다(`KAFKA_QUARANTINE_REQUIRED`).
- handler timeout이 지나도 handler가 끝날 때까지 partition slot을 잡고 있는다. `CompletableFuture`를
cancel해도 handler는 멈추지 않으므로, slot을 먼저 풀면 같은 offset이 두 번 동시에 돈다.
## RabbitMQ: delayed retry queue
core broker에 per-message delay가 없으므로 **TTL + DLX**로 구현한다.
retry queue의 `x-message-ttl`이 만료되면 `x-dead-letter-exchange`를 통해 work queue로 되돌아간다.
주의: TTL 만료는 큐 **head**에서 평가된다. 하나의 retry queue에 서로 다른 delay를 섞으면
독립적으로 만료되지 않는다.
`basic.nack(requeue=true)`는 사용하지 않는다. delay 없이 큐 head로 되돌리므로 hot loop가 된다.
## DLQ: publish 확인 후 settlement
이것이 dead lettering이 데이터 손실이 되지 않게 하는 **유일한** 불변식이다.
```text
DLQ envelope 생성 (원래 messageId 유지)
→ DLQ publish
→ CONFIRMED 이면 source settlement
→ REJECTED / AMBIGUOUS 이면 source를 settlement하지 않음
```
source를 먼저 ACK하면, DLQ publish가 실패했을 때 메시지의 사본이 **어디에도 남지 않는다**.
broker는 이미 해제했고 DLQ는 받지 못했다.
AMBIGUOUS DLQ publish는 중복을 만든다. 이것이 의도된 trade다. DLQ는 사람이 읽는 곳이고
중복은 알아볼 수 있지만, 손실은 복구할 수 없다.
## DLQ envelope 내용
reserved header에만 기록한다. payload에 넣지 않는다.
```text
msg.failure-category, msg.failure-code, msg.origin-destination,
msg.retry-attempt, msg.first-failure-at, msg.last-failure-at
```
stack trace, exception message, secret header, 실제 key는 **넣지 않는다**.
DLQ는 원본 topic보다 오래 보관되고 더 많은 사람이 읽는다.
## Redrive
M4 Admin 전용이다. `DestructiveOperationGuard`를 통과해야 한다.
- admin credential 필요 (application runtime은 보유하지 않는다)
- 유효기간 내 `AdminApproval` 필요
- dry-run은 항상 허용 (계획이 공짜여야 사람이 계획한다)
- batch 상한 100건
- source == target 금지
- `redriveId`는 `messageId`와 별개다. 재구동 루프를 식별하기 위해서다.
redrive도 **publish → settlement** 순서다. republish가 confirm되지 않은 메시지는
DLQ에 남는다.
-112
View File
@@ -1,112 +0,0 @@
# Messaging 보안
## Credential 분리
producer / consumer / admin은 **서로 다른 credential**이다.
`MessageSecurityValidator`가 startup에서 강제한다.
```text
producer credential == consumer credential → 실패
admin credential == producer|consumer → 실패
production 프로필에 admin credential 존재 → 실패
```
마지막 규칙이 "애플리케이션은 topic을 purge할 수 없다"를 **구조적으로** 만든다.
runtime이 admin 자격 증명을 아예 보유하지 않으므로, 침해된 handler가 상승시킬 대상이 없다.
## Production 필수 조건
- TLS 활성
- TLS hostname verification 활성
- 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 금지.
RabbitMQ는 추가로 publisher confirm, publisher return, `mandatory=true`,
durable work queue의 quorum queue, consumer auto-ack 금지.
## Credential은 값이 아니라 참조다
`BrokerCredentialProfile`의 어떤 variant도 secret을 담지 않는다.
식별자만 보관하고 connect 시점에 `CredentialProvider`로 해석한다.
heap dump나 설정 출력에서 사용 가능한 credential이 나오지 않는다.
`CredentialIds`는 `bearer `, `sk-`, `-----begin`, `eyJ` 같은 접두사를 거부한다.
참조가 들어갈 자리에 secret 자체를 붙여넣는 가장 흔한 사고를 막는다.
SASL(PLAIN·SCRAM) 사용자 이름도 `CredentialProvider.username(credentialId)`가 준다. credential id는
저장소 안의 참조이지 broker가 아는 사용자 이름이 아니다. provider가 이름을 주지 않으면 기동에
실패한다.
key store·trust store는 경로만 설정에 둔다. 비밀번호는 credential id로 provider가 해석한다
(`configuration-reference.md` 보안 절).
## Rotation
`CredentialRotationPlan.isDue()`는 만료 **전에** 참이 된다.
broker가 연결을 거부하기 시작한 시점에는 이미 publish가 실패하고 consumer가 멈춰 있다.
Kafka SASL credential은 producer를 다시 만들지 않고 바뀐다. JAAS 설정에는 login module 이름만
있고, `KafkaCredentialCallbackHandler`가 연결이 인증할 때마다 `CredentialRuntimeRegistry`에서
사용자 이름과 비밀번호를 읽는다. registry는 provider가 준 만료 시각의 rotation lead(기본 30분)
안으로 들어오면 새로 가져오므로, 새 연결과 재인증(broker `connections.max.reauth.ms`)이 새 값을
쓴다. 만료 시각을 주지 않는 provider의 credential은 캐시된 값을 계속 쓴다.
key store·trust store 비밀번호는 예외다. Kafka가 SSL context를 만들 때 한 번 읽으므로 바꾸려면
producer를 다시 만들어야 한다(재기동).
transport 세대 교체(`DefaultMessagingRuntimeRegistry.install()`)는 transport 자체를 바꿀 때 쓴다.
새 세대를 원자적으로 게시하고, 이전 세대는 마지막 lease가 닫힐 때까지 열려 있다가 닫힌다.
drain deadline이 이 대기를 제한한다.
## Header
금지 header는 application·platform 양쪽에서 거부한다.
```text
Authorization, Proxy-Authorization, Cookie, Set-Cookie,
access_token, refresh_token, api_key, password, client_secret
```
credential이 header에 들어가면 broker storage, DLQ dump, 운영 도구에 남는다.
downstream redaction으로는 되돌릴 수 없다.
예약 header(`msg.*`, `traceparent`, `tracestate`, `baggage`)는 platform만 쓴다.
application이 `msg.id`를 설정할 수 있으면 Inbox 중복 제거와 DLQ 상관관계가 의존하는
logical identity가 호출자 제어가 된다.
## ACL
publisher가 broker ACL **이전에** 검사한다(`PUBLISH_FORBIDDEN`).
broker ACL 거부는 애플리케이션 컨텍스트가 없는 연결 수준 오류로 도착하므로
"어느 모듈이 어디에 publish하려 했는가"가 조사 대상이 된다.
publish 가능한 destination은 선언된 destination이다. broker에 `app.messaging.security.<broker>`
항목이 있으면 그중 `access.publishable`에 적힌 것만 남는다(빈 목록이면 publish 불가).
## 관측성 누출
`MessagingRedactor`는 denylist다.
- secret: authorization, cookie, token, password, secret, credential
- per-message identity: messageId, correlationId, causationId, partitionKey, key, offset, deliveryTag, sequence
- payload: payload, body, data
- 예외 상세: exceptionMessage, stackTrace
identity를 지우는 이유는 두 가지다. bounded metric을 message당 하나의 series로 만들고,
support log를 재식별 표면으로 만들기 때문이다.
`CardinalityGuard`는 dimension당 값 개수를 상한한다.
cardinality 사고는 점진적이지 않다. 테스트 10건에서는 멀쩡하고 운영에서 백엔드를 죽인다.
## 감사
`MessagingAuditEvent`는 replay, redrive, offset reset, purge, delete를 기록한다.
subject(운영자 identity), approval ticket, 그리고 redactor를 통과한 details만 담는다.
누가 무엇을 했는지 증명하되 payload의 두 번째 사본이 되지 않는다.
-154
View File
@@ -1,154 +0,0 @@
# Messaging 지원 매트릭스
플랫폼이 **무엇을 보장하는지**와 **무엇을 보장하지 않는지**를 브로커별로 고정한다.
여기 없는 조합은 지원되지 않는다.
> **등급은 증거를 따른다.** `CompatibilityMatrix.Entry.hasLiveBrokerCertification()`은 선언된
> boolean이 아니라 `CertifiedEvidence`가 가진 레인 증거에서 파생된다. 레인이 생겨 증거를 내면 등급은
> 코드 수정 없이 따라 올라간다.
> **삭제된 어댑터.** RabbitMQ(선택할 수 없던 validator·설정 모음), Pulsar·NATS JetStream·Kafka Share
> Group(Experimental, SDK 없는 seam), Spring Cloud Stream bridge, Debezium outbox 매핑은 2026-09-25에
> 삭제했다. 복구 경로는 `docs/capability-status.md`의 제거 표에 있다.
> **인증 근거.** 이 표의 버전은 이 저장소의 컨테이너 레인이 실제로 실행한 이미지다. 이전 판은
> Kafka 4.2/4.3을 선언했지만 fixture는 `apache/kafka:4.1.0`, lockfile client는 4.1.1이었다 — 표와
> 코드 상수가 서로 일치했을 뿐 어느 쪽도 실행된 적이 없었다. 장애 시나리오 커버리지도 마찬가지로
> `BrokerFailureMatrix.shipped()` 하드코딩이 아니라 레인이 낸 증거(`BrokerCertificationEvidence`)에서
> 나온다. 증거가 없는 조합은 `NOT_COVERED`다 (MSG-014).
> **모듈 이름과 런타임 편입.** 관계형 신뢰성 구현은 `messaging-reliability-jdbc-postgresql`,
> 그 port만 보는 relay·consumer 로직은 `messaging-reliability`다(2026-09-28에
> `messaging-outbox-jdbc-postgresql` / `messaging-inbox-jdbc-postgresql`을 이렇게 나눴다). 그 전에는
> `-jpa`로 불렸다. 구현은 Spring JDBC이고 SQL은 PostgreSQL 전용(`jsonb`,
> `FOR UPDATE SKIP LOCKED`, `ON CONFLICT`, `TIMESTAMPTZ`)이므로, 그 이름은 쓰지 않는 기술을
> 광고하고 vendor 중립 port(`messaging-reliability-api`)의 위치를 가렸다 (MSG-023).
>
> `modules.json`은 messaging leaf의 `gradle_path`와 허용 의존성을 관리하지만
> `runtime_memberships` 필드는 없다. 실제 런타임 편입은 `app-bootstrap`의 Gradle 의존성과 starter /
> auto-configuration 경로가 결정한다. 아래 등급은 "무엇이 증명되었는가"를 말하며 런타임 편입 여부와
> 같은 축이 아니다. 자세한 composition/cutover 상태는 `src/platforms/messaging/AGENTS.md`가 소유한다.
## 브로커 등급
| 브로커 | 등급 | 인증 기준 | Stable 기능 | 제한 |
|---|---|---|---|---|
| Kafka | Stable | 4.1.x | producer idempotence, consumer group, batch, pause/resume, replay, transaction capability | Share Group 미지원 |
| Artemis/JMS | Extension | 범위 밖 | adapter SPI만 | 별도 ADR + Contract Suite 통과 필요 |
## Capability 매트릭스
`MessagingCapabilities`가 런타임에 선언하는 값이다. `false`인 기능을 요구하는 destination profile은
**startup에서 실패**하며, 조용히 약화되지 않는다.
| Capability | Kafka |
|---|---|
| brokerAcknowledgement | O |
| replicationOrPersistenceEvidence | O |
| perMessageSettlement | O |
| batchSettlement | O |
| orderedStream | O |
| keyedOrdering | O |
| replay | O |
| delayedDelivery | X |
| brokerTransaction | O |
| deduplicatedPublish | O |
| nativeDeadLetter | X |
| topologyManagement | O |
## 기능 등급
| 기능 | 등급 |
|---|---|
| Typed Publish·Consume | Stable M1 |
| At-least-once contract | Stable |
| Ambiguous publish 결과 | Stable |
| handler 성공 후 자동 settlement | Stable M1 |
| Batch / Manual settlement / Pause·Resume / Delayed / Replay 요청 | M2 |
| Broker transaction / partition / routing / subscription | M3 |
| Replay 실행 / Redrive / offset reset / purge / delete | M4 Admin |
## 무엇이 "Stable"을 증명하는가
Stable 등급은 두 가지를 **모두** 통과해야 한다. `CompatibilityMatrixTest`가 이 규칙을 강제한다.
### 1. 공유 Contract Suite (`MessagingAdapterContract`, 7개)
Kafka가 7개 테스트를 변경 없이 통과한다. 결정적 하네스를 쓰므로
확인 유실·settlement 유실 같은 장애를 요청 시점에 재현할 수 있다.
### 2. 실 브로커 인증 (Testcontainers)
| 스위트 | 무엇을 증명하는가 |
|---|---|
| `KafkaBrokerIT` | `acks=all`이 실제 replication 증거를 만든다 / 잘못된 토픽은 `REJECTED` / 발행-소비 왕복에서 identity 보존 및 contiguous commit |
| `KafkaAmbiguityChaosIT` | 브로커를 `docker pause`로 멈춘 상태의 publish가 **`AMBIGUOUS`** 로 보고된다 (broker acceptance 없음, confirmation level `NONE`, 비-retryable) |
| `KafkaBrokerCertificationIT` | 인증 레인. Toxiproxy를 broker 앞에 두고 connection cut / confirm 유실 / 지연 / settlement 유실을 각각 주입하고, 통과한 시나리오마다 `BrokerCertificationEvidence` 한 줄을 manifest에 쓴다 |
| `OutboxPostgresIT` | 롤백된 트랜잭션은 발행 가능한 행을 남기지 않는다 / `SKIP LOCKED` lease가 두 relay를 분리한다 / ambiguous 행이 같은 `messageId`로 재클레임된다 |
| `InboxPostgresIT` | 재전달이 side effect를 두 번 적용하지 않는다 / 롤백은 예약도 되돌린다 |
Docker가 없으면 `DockerAvailability` 가드로 skip되며, 이 표의 항목은 그때 **검증되지 않은 것**으로 취급한다.
`KafkaBrokerCertificationIT`만 예외다 — 인증 레인은 가드를 달지 않고 Docker가 없으면 실패한다. skip하는
레인은 아무도 켜지 않은 브로커에 대해 성공을 보고하기 때문이다. 그래서 이 레인은 `test`에서 태그로
제외되고 `messagingCertificationTest`로만 실행된다.
### 3. 장애 시나리오 커버리지 (`BrokerFailureMatrix`)
`NetworkFaultScenario`가 5개 시나리오와 **각각의 기대 결과**를 코드로 고정한다. 기대 결과를 어댑터별로
두지 않는 것이 핵심이다 — 어댑터마다 다른 답을 허용하면 공유 계약이 존재할 이유가 없다.
| 시나리오 | 시점 | 기대 결과 | 이유 |
|---|---|---|---|
| `connection-refused` | 전송 전 | `REJECTED` | 바이트가 나가지 않았으므로 broker가 가질 수 없다 |
| `connection-cut-after-write` | 전송 후 | `AMBIGUOUS` | broker가 저장했고 confirm만 유실됐을 수 있다 |
| `confirm-timeout` | 전송 후 | `AMBIGUOUS` | timeout은 부재의 증거가 아니라 증거의 부재다 |
| `settlement-lost` | settlement 중 | `REDELIVERED` | 미settlement 메시지는 재전달이 설계다 |
| `high-latency` | 전송 후 | `AMBIGUOUS` | 판단 시점에는 confirm 유실과 구별할 수 없다 |
`CrossBrokerContractSuite`가 릴리스 게이트로 이를 강제한다. Stable 어댑터는 5개 전부를 **실 브로커에서**
커버해야 하고, Experimental 어댑터는 `LIVE_BROKER` 커버리지를 주장할 수 없다. 커버리지는 *능력*이 아니라
*무엇을 실제로 돌렸는지*의 기록이다.
**증거의 출처.** `CertifiedEvidence`는 더 이상 손으로 쓴 목록이 아니라
`messaging-testkit/src/main/resources/messaging/broker-certification-evidence.jsonl`을 읽는다. 그 파일은
`messagingCertificationTest` 레인이 실제 Kafka 컨테이너에 장애를 주입하며 만들어낸 출력이고,
`verifyMessagingCertificationEvidence`가 커밋된 manifest와 이번 실행의 출력을 대조해 다르면 빌드를
실패시킨다. 즉 **manifest를 손으로 고치면 게이트가 깨지고, 레인을 돌리면 manifest가 다시 쓰인다.**
오늘 Kafka가 가진 증거는 `connection-cut-after-write` · `confirm-timeout` · `high-latency` ·
`settlement-lost` 네 개다. `connection-refused`는 남은 gap이며 그 이유가 있다 — Kafka producer는 연결
존재 여부를 알기 전에 레코드를 버퍼에 넣으므로, 연결 거부는 전송에 대해 아무것도 증명하지 못하는
delivery timeout으로 나타난다. 이를 `REJECTED`로 보고하는 것은 이 플랫폼이 금지한 추측이므로,
시나리오는 `CertifiedEvidence.knownGaps`가 이름으로 들고 있는 미커버 항목으로 남는다.
### 실 브로커가 실제로 잡아낸 결함
이 스위트들은 장식이 아니다. 작성 과정에서 결정적 테스트가 통과하는데 실 인프라에서 실패한
결함을 두 건 잡았다.
1. **Outbox `IN_FLIGHT` 고아 행** — lease 쿼리가 `PENDING`/`AMBIGUOUS`만 클레임 대상으로 봐서,
publish 도중 죽은 relay가 남긴 행이 lease 만료 후에도 영영 회수되지 않았다.
2. **Rabbit confirm 경합**(2026-09-25에 삭제된 Rabbit transport) — transport가 publish *후에* confirm을 등록해서, 연결 스레드에서
confirm이 먼저 도착하면 유실되고 호출자가 무한 대기했다.
둘 다 인메모리 double이 실제보다 관대해서 통과하고 있었다.
## 명시적 비지원
- 공통 `EXACTLY_ONCE` 설정 — `DeliveryGuarantee`에 상수가 존재하지 않는다.
- 전역 순서 — `OrderingScope`에 `GLOBAL`이 존재하지 않는다.
- DB와 broker의 자동 원자 transaction, 기본 XA
- Java native serialization
- 무제한 payload·header, 무한 retry
- 운영 application에서의 topology 파괴 작업
- 일반 애플리케이션에 raw broker client 반환
- DLQ publish 확인 전 source ACK
### Optional mapping utilities
- `messaging-cloudevents`는 starter runtime에 자동 편입되지 않는 **opt-in mapping utility**다.
내부 envelope와 CloudEvent 객체 사이의 제한된 profile mapping을 제공하지만 binary/structured
CloudEvents wire mode 전체를 구현하거나 임의 CloudEvents producer와의 1.0 interoperability를
인증하지 않는다.
- `messaging-claim-check`도 starter에 편입되지 않는 opt-in utility다.
+1 -1
View File
@@ -2836,7 +2836,7 @@ env_keys:
- name: APP_MESSAGING_BROKER
# source: messaging multi-broker redesign 2026-06-16 — 활성 broker 하나를 고른다
# (app.messaging.broker=<brokerId>). 들여온 메시징 플랫폼이 읽는다. 옛 Kafka 전용 APP_MESSAGING_KAFKA_ENABLED를
# (app.messaging.broker=<brokerId>). 메시징 라이브러리(dev.cakit.messaging)가 읽는다. 옛 Kafka 전용 APP_MESSAGING_KAFKA_ENABLED를
# 대신한다. 애플리케이션 bridge는 이제 읽지 않는다: 읽던 옛 KafkaSender seam은 canonical outbox와 함께
# 지웠다(2026-09-28).
type: string
+13
View File
@@ -162,6 +162,19 @@ PR 단계 trivy 검사(`dependency-vulnerability.yml`의 HIGH·CRITICAL 단계)
| B-55 | 삭제: `src/platforms/grpc`, `src/platforms/grpc-advanced`, `src/platforms/optional-build`(두 번째 빌드 `optional-platforms` 전체), registry의 `"build": "optional-grpc"` 9행, workflow job `ci-quality-gates.yml` `optional-platforms`·`grpc-proto-buf`(그리고 `release-gate`의 두 `needs`), `integration-main.yml`의 optional 성능 단계와 job `grpc-optional-platform-integration`, `release.yml` job `grpc-stable-release-gate`(그리고 이미지 job의 `needs` 한 줄), 살아 있는 문서 `docs/compatibility/`(폴더째), `docs/runbooks/grpc-platform-operations.md`·`grpc-advanced-capabilities.md`. 새 자리는 grpc-library repo이고 같은 이름의 파일이 이력째 있다. 기록(`docs/adr/ADR-GRPC-*` 7개, `docs/design/2026-08-30-grpc-platform-adaptation-design.md`)은 본문을 두고 머리 블록 「현재 정본」만 그 repo를 가리키게 했다. 사본이 그 repo에도 있다. 그 repo에서 Maven group과 Java 패키지는 `dev.cakit.grpc`, proto 패키지는 `cakit.grpc.common.v1`이다(템플릿 재사용 체크리스트의 `dev.caskeleton` 바꾸기와 겹치지 않게 다른 이름) | 이 경로를 고친 서비스는 「수정 대 삭제」 충돌이 난다. `project(':grpc:…')`·`project(':grpc-advanced:…')`나 `-p platforms/optional-build`를 쓴 서비스는 빌드가 실패한다 | 쓰지 않았으면 삭제를 그대로 받는다. 썼으면 grpc-library 첫 버전(`1.0.0`, 소유자가 태그를 단 뒤)을 좌표 `dev.cakit.grpc:<모듈>:1.0.0`으로 받고(저장소 선언은 그 repo README 「받는 법」), import를 `dev.caskeleton.grpc` → `dev.cakit.grpc`로 바꾼다 | design-docs `repo-structure/05-library-repos.md` 4·13절, `docs/work/reference/related-repos.md` |
| B-56 | 빌드 규칙·카탈로그: build-logic의 `ca.grpc-platform-module`·`ca.optional-architecture-registry` 플러그인과 `MainBuild`(두 번째 빌드에서 주 빌드를 찾던 것)를 지웠다. 도구 설정·테스트 이미지 목록·registry는 Gradle 루트(`src/`)에서만 찾는다. 카탈로그에서 `protobufPlugin`·`protobuf-java-grpc`·`protoc`·plugin `protobuf`를, SpotBugs 제외에서 gRPC 플랫폼 클래스 줄을 지웠다 | 서비스 leaf가 `ca.grpc-platform-module`이나 `libs.protoc`·`libs.protobuf.java.grpc`·`libs.plugins.protobuf`를 쓰면 빌드가 실패한다. `src/` 밖 두 번째 빌드에서 이 build-logic을 쓰던 서비스는 도구 설정을 못 찾는다 | 그 leaf `build.gradle`에서 `io.grpc:grpc-bom` import와 protobuf 플러그인 버전을 직접 적거나, 지운 카탈로그 항목을 서비스 카탈로그에 다시 더한다 | 같은 설계 13.1절 2단계 |
### 3.9 메시징 플랫폼 — 별도 repo `messaging-library`로 옮기고 버전 1.0.0으로 받는다
이 절도 위 머리의 범위보다 뒤에 main에 들어간다. 범위: `2959eff0..claude/x3-messaging-library-1aa3fa`(2026-11-08, 같은
소유자 결정, design-docs `repo-structure/05-library-repos.md` 13.1절 3~5단계). 메시징은 템플릿 adapter 넷이 쓰므로, 라이브러리를
먼저 `dev.cakit.messaging` 1.0.0으로 Gitea Packages에 배포하고 템플릿이 그 버전을 받게 바꿨다. 코드와 이력은
https://git.learn.hyeonworks.com/donghyeon.kang/messaging-library 에 있다. 동작은 같다(같은 소스, 패키지 이름만 바뀜).
| # | 무엇이 바뀌었나 | 파생 서비스 증상 | 할 일 | 근거 |
|---|---|---|---|---|
| B-57 | 삭제: `src/platforms/messaging`(19개 모듈)과 빈 `src/platforms/`, registry의 메시징 19행, workflow `messaging-certification.yml`, 저장소 계약 테스트 `MessagingPublicSurfaceContractTest`(라이브러리 repo로), 살아 있는 문서 `docs/messaging/`(폴더째, 같은 이름으로 라이브러리 repo에), SpotBugs 제외의 메시징 클래스 줄, 카탈로그의 메시징 전용 항목(`avro`, `cloudevents`, `protobuf` 4.33.2와 `protobuf-java`). `check-repo-layout.py` 허용 목록에서 `platforms`를 뺐다. 메시징 기록(`docs/design/2026-08-10-messaging-platform-design.md` 등)은 본문을 두고 머리 블록 「현재 정본」만 고쳤다 | 이 경로를 고친 서비스는 「수정 대 삭제」 충돌. `project(':messaging:…')`를 쓴 자기 leaf는 빌드가 실패한다. `src/platforms/` 아래 자기 폴더를 둔 서비스는 `check-repo-layout.py`가 실패한다 | 메시징 코드를 고쳤으면 그 수정을 messaging-library repo로 보낸다(`docs/work/reference/related-repos.md` 2절). 자기 leaf의 `project(':messaging:<모듈>')`은 B-58처럼 좌표로 바꾼다 | design-docs `repo-structure/05-library-repos.md` 4·13절 |
| B-58 | 받는 법: `src/settings.gradle`에 Gitea Packages 저장소를 `exclusiveContent`(group `dev.cakit`와 그 아래만)로 더했다. 카탈로그에 `messagingLibrary = "1.0.0"`과 모듈 여섯(`libs.messaging.core.api` 등). 쓰는 leaf(`adapter:outbound:messaging`, `adapter:outbound:messaging-kafka`, `adapter:inbound:messaging`, 시험만 `composition:outbox-relay`·`adapter:outbound:persistence-jpa`)가 좌표로 받는다. Java 패키지 `dev.caskeleton.messaging` → `dev.cakit.messaging`, auto-configuration 이름 `dev.cakit.messaging.autoconfigure.MessagingPlatformRootAutoConfiguration`. 그대로인 것: 설정 키 `app.messaging.*`, env 키, Flyway 위치 `db/migration/messaging`과 파일, 표 이름 | 메시징 타입을 import한 자기 코드가 컴파일되지 않는다. `afterName`·`beforeName`으로 플랫폼 root 이름을 적은 자기 auto-configuration은 순서 제약이 조용히 사라진다. 캐시가 빈 빌드(새 기계, 이미지 builder)는 `git.learn.hyeonworks.com`에 닿아야 한다 | import와 이름 문자열의 `dev.caskeleton.messaging`을 `dev.cakit.messaging`으로 바꾼다(템플릿 재사용 체크리스트의 `dev.caskeleton` 바꾸기에 넣지 않는다). merge 뒤 `./gradlew resolveAndLockAll --write-locks`. 빌드 기계가 Gitea에 닿는지 본다(공개 owner라 토큰은 필요 없다) | messaging-library `CHANGELOG.md` 1.0.0 |
| B-59 | registry 칸 둘: 맨 위 `library_groups`(`["dev.cakit"]`)와 행마다 `allowed_libraries`(`group:artifact`). 방향 검사(`verifyModuleDependencyDirection`)가 소유 group 라이브러리의 운영 선언(`runtimeOnly` 포함)과 컴파일에서 보이는 모듈을 그 칸과 대조한다. build-logic `ModuleRegistry`·`VerifyModuleDependencyDirectionTask`가 바뀌었다 | 자기 leaf가 `dev.cakit.*` 모듈을 칸에 적지 않고 쓰면 `verifyCleanArchitectureDependencies`가 「forbidden library dependencies」로 실패한다. registry를 읽는 자기 도구가 모르는 키를 거절하면 실패한다 | 그 leaf 행에 `allowed_libraries`를 적는다(`src/config/architecture/README.md` 「별도 repo 라이브러리」). build-logic을 고쳐 쓴 서비스는 두 파일 병합 충돌을 푼다 | 같은 설계 10.2절 T2(Q11) |
## 4. DB 마이그레이션
### 4.1 새 버전과 영향
+1 -1
View File
@@ -54,7 +54,7 @@ design-docs `conventions/delegation-loop.md` 3절 순서대로 한다: 크기
| inbound 전송 | `src/adapter/inbound/*`. gRPC 플랫폼 라이브러리는 별도 repo `grpc-library`에서 고친다(`reference/related-repos.md`) |
| persistence | `src/adapter/outbound/persistence-*`, 마이그레이션 |
| outbound capability | 그 밖의 `src/adapter/outbound/*`, 멱등성 store |
| messaging | `src/platforms/messaging/*`, `src/adapter/outbound/messaging` |
| messaging | `src/adapter/inbound/messaging`, `src/adapter/outbound/messaging*`. 메시징 라이브러리는 별도 repo `messaging-library`에서 고친다(`reference/related-repos.md`) |
| bootstrap·build·CI | `src/app-bootstrap`, `src/composition/*`, `src/build-logic`, `src/build.gradle`, `.github/` |
| 보안(영역을 가로질러) | 인증·인가 체인, 비밀, 공개 경로 |
| 문서 | `docs/` |
+3 -3
View File
@@ -76,7 +76,7 @@
| --- | --- | --- | --- |
| outbox relay·멱등성 executor 조립 | app-bootstrap이 아니라 별도 `composition:*` 모듈 | 소유자 | 결정 3 |
| 새 leaf | `composition:durable-operation`, `adapter:inbound:messaging` 등록 승인 | 위임 | `1101` 15절 |
| edge 없는 복사본 | 템플릿 leaf는 `shared-contract` edge를 더해 정본을 쓴다. vendored(`messaging:*`)와 별도 repo 라이브러리는 복사본을 두고 family `AGENTS.md`(라이브러리는 그 모듈)에 이유 | 위임 | `1101` 15절(01-11) |
| edge 없는 복사본 | 템플릿 leaf는 `shared-contract` edge를 더해 정본을 쓴다. 별도 repo 라이브러리(messaging-library, grpc-library)는 복사본을 두고 그 repo의 모듈 지침에 이유 | 위임 | `1101` 15절(01-11) |
| caller 트랜잭션 guard | `persistence-notification`·`persistence-fileserver` → `persistence-jpa` edge, `CallerTransaction` 하나 | 소유자 | 결정 33 |
| id 포트 | notification·fileserver id 포트를 domain `IdFactory`로 옮기지 않음(보류) | 소유자 | 결정 34 |
| 소비자 없는 필드 | principal tenant, GraphQL Spring Security resolver, 가명화 키 분리는 하지 않음(보류) | 소유자 | 결정 35 |
@@ -85,8 +85,8 @@
| `@SystemInvoked` | bean으로 등록돼 있으면 기동 실패, inbound adapter가 직접 부르지 못하게 ArchUnit | 위임 | `1103` 4절(RR-01-02) |
| 시스템 호출 경로 | 사용자가 닿는 전송(web·GraphQL·gRPC·WebSocket)만 `@SystemInvoked`에 닿지 못한다. 메시지 소비자·스케줄러는 `@SystemCaller(reason)` 표시로 허용 | 위임 | `1103` 9.1절(RR-01-12), 10절 r5-b |
| 배치 규칙 검사 | 저장소 루트와 `src/` 최상위 허용 목록을 `scripts/check-repo-layout.py`로 PR에서 막는다. 리뷰 기준에도 넣는다(매뉴얼 보강 작업) | 소유자(2026-11-07) | design-docs `repo-structure/README.md` 3.1절, `repo-structure/01-backend-layout.md` 10.3절 |
| `src/` 배치 | 들여온 플랫폼 넷(`messaging`, `grpc`, `grpc-advanced`, optional 빌드)을 `src/platforms/` 아래로 묶는다. registry `source_path`만 바꾸고 Gradle 경로는 그대로 둔다. `build-logic`·`gradle`·`config`는 Gradle 루트 표준이라 남기고, `composition`은 조립 계층이라 옮기지 않는다. `config/`에서 기능 하나가 주인인 데이터 파일은 그 leaf로 보낸다. Gradle 루트를 저장소 루트로 옮길지는 CI 재편 때 다시 본다. gRPC 둘과 optional 빌드는 2026-11-08 별도 repo로 나갔다(아래 「라이브러리 repo」) | 소유자(2026-11-07) | design-docs `repo-structure/README.md` 3.1절, `repo-structure/01-backend-layout.md` 6.1절 |
| 라이브러리 repo | 프로젝트 계층이 아닌 라이브러리(메시징, gRPC)는 템플릿에 두지 않는다. 라이브러리마다 별도 repo에서 고치고 Gitea Packages에 버전으로 배포하며, 템플릿은 쓰는 라이브러리만 카탈로그 좌표로 받는다. gRPC가 먼저 `grpc-library`로 옮겼다(2026-11-08, 템플릿 소비자 없음이라 카탈로그 항목도 없음). 목록과 고치는 법은 `related-repos.md` | 소유자(2026-11-07) | design-docs `repo-structure/README.md` 3.5절, `repo-structure/05-library-repos.md` 15절 |
| `src/` 배치 | 들여온 플랫폼 넷(`messaging`, `grpc`, `grpc-advanced`, optional 빌드)을 `src/platforms/` 아래로 묶는다. registry `source_path`만 바꾸고 Gradle 경로는 그대로 둔다. `build-logic`·`gradle`·`config`는 Gradle 루트 표준이라 남기고, `composition`은 조립 계층이라 옮기지 않는다. `config/`에서 기능 하나가 주인인 데이터 파일은 그 leaf로 보낸다. Gradle 루트를 저장소 루트로 옮길지는 CI 재편 때 다시 본다. 넷 모두 2026-11-08 별도 repo로 나갔고 `src/platforms/`는 지웠다(아래 「라이브러리 repo」) | 소유자(2026-11-07) | design-docs `repo-structure/README.md` 3.1절, `repo-structure/01-backend-layout.md` 6.1절 |
| 라이브러리 repo | 프로젝트 계층이 아닌 라이브러리(메시징, gRPC)는 템플릿에 두지 않는다. 라이브러리마다 별도 repo에서 고치고 Gitea Packages에 버전으로 배포하며, 템플릿은 쓰는 라이브러리만 카탈로그 좌표로 받는다. gRPC가 먼저 `grpc-library`로 옮겼다(2026-11-08, 템플릿 소비자 없음이라 카탈로그 항목도 없음). 메시징은 `messaging-library` 1.0.0으로 옮기고 쓰는 leaf가 카탈로그 `messagingLibrary`로 받는다(2026-11-08). 라이브러리 edge는 registry 「허용 라이브러리」 칸(`library_groups`·`allowed_libraries`)이 막는다(설계 Q11 T2). 목록과 고치는 법은 `related-repos.md` | 소유자(2026-11-07) | design-docs `repo-structure/README.md` 3.5절, `repo-structure/05-library-repos.md` 15절 |
| 개발 compose 파일 | 저장소 루트에 `compose.yaml` 하나. 뒷단 서비스는 capability 이름 profile로 고르고, 마운트하는 보조 파일은 `compose/`에 둔다. 테스트 lane fixture는 그 lane을 가진 leaf로 보낸다(compose lane → app-bootstrap `compose-lanes/`, Redis topology → redis-sdk, NFS → fileserver). `docker-compose.dev.yml`은 `dev` 배포 프로필이 뜨는지 보는 lane fixture로 app-bootstrap에 둔다 | 소유자(2026-11-07) | design-docs `repo-structure/README.md` 3.1절, `repo-structure/01-backend-layout.md` 6.3절 |
| 인프라 실행 파일 | nginx 설정, Kubernetes PVC job, DB 역할 SQL은 이 repo에서 지우고, 기능이 운영 환경에 요구하는 조건만 그 기능 문서에 적는다. 아무도 쓰지 않는 infra 폴더 파일도 지운다. 지운 목록은 `docs/upgrade/2026-11-maturity-review.md` B-50 | 소유자(2026-11-07) | design-docs `repo-structure/README.md` 3.1절, `repo-structure/01-backend-layout.md` 6.3절 |
| 샘플 모듈 | 샘플 leaf와 샘플 전용 Dockerfile을 폴더째 지운다(지운 경로는 `docs/upgrade/2026-11-maturity-review.md` B-49). 역할은 옮기지 않는다. 샘플 안에만 있던 템플릿 검사(OpenAPI 스냅숏, Date 헤더, 가상 스레드 MDC)도 함께 지운다. 예시는 매뉴얼과 생성 명령 출력이 맡는다 | 소유자(2026-11-07) | design-docs `repo-structure/README.md` 3.1절, `repo-structure/01-backend-layout.md` 6.2절 |
+1 -1
View File
@@ -121,7 +121,7 @@
| 규칙을 일부러 다르게 둔 타입 | 그 타입의 Javadoc |
| 정적 분석 제외 | 제외 항목 옆 이유(`src/config/spotbugs/exclude-test.xml` 등) |
| 규칙의 예외 경로 | 이유를 요구하는 표시(`@SystemCaller(reason)`) |
| 복사본을 남긴 이유 | 가까운 `AGENTS.md`(예: `src/platforms/messaging/AGENTS.md`) |
| 복사본을 남긴 이유 | 가까운 `AGENTS.md`. 복사본을 둔 leaf의 `build.gradle`이나 그 폴더의 `AGENTS.md`에 적는다 |
| 되돌리기 비싼 선택 | `docs/adr/ADR-<영역>-<번호>-<제목>.md` |
## 패턴을 더하는 법
+1 -1
View File
@@ -190,7 +190,7 @@ for k in tests skipped failures errors; do cat $(find "$x" -name 'TEST-*.xml') |
| 장치 | 고정하는 것 | 단계 |
| --- | --- | --- |
| 자원 한계 lane | Tomcat·Jetty 부하·느린 클라이언트·종료, HTTP client 풀·스트리밍·재시도, Hikari 풀 | `performanceCheck` |
| JMH 벤치마크 | `src/platforms/messaging/messaging-kafka/src/jmh`, `src/platforms/messaging/messaging-testkit/src/jmh`, `src/adapter/outbound/httpclient/src/jmh` | 명시 실행 |
| JMH 벤치마크 | `src/adapter/outbound/httpclient/src/jmh`(메시징 벤치마크는 messaging-library repo로 옮겼다) | 명시 실행 |
## 6. 게이트를 믿을 조건 — 거짓 통과 막기
+23 -15
View File
@@ -6,34 +6,42 @@
| repo | 무엇 | Maven group | 카탈로그 칸 | 쓰는 leaf |
| --- | --- | --- | --- | --- |
| [messaging-library](https://git.learn.hyeonworks.com/donghyeon.kang/messaging-library) | 메시징 제품(발행·소비 API, Kafka transport, outbox·inbox, 인증 증거) | `dev.cakit.messaging` | `messagingLibrary` | `adapter:outbound:messaging`(core-api), `adapter:outbound:messaging-kafka`(starter-kafka, `runtimeOnly`), `adapter:inbound:messaging`(core-api, reliability, reliability-api, reliability-jdbc-postgresql). 시험만: `composition:outbox-relay`(starter, `testCompileOnly`), `adapter:outbound:persistence-jpa`(reliability-jdbc-postgresql jar의 migration) |
| [grpc-library](https://git.learn.hyeonworks.com/donghyeon.kang/grpc-library) | gRPC 플랫폼(Stable 7, advanced 2) | `dev.cakit.grpc` | 없음(채택 전) | 없음. `adapter:inbound:grpc`는 `io.grpc`를 직접 쓴다. 채택은 별도 결정이다 |
| `messaging-library` | 메시징 제품 | `dev.cakit.messaging` | (옮긴 뒤 `messagingLibrary`) | 아직 `src/platforms/messaging`에 있다. 다음 분리 작업에서 옮긴다 |
고치는 법·게이트·릴리스는 각 repo의 `docs/work/`다. 이 repo의 매뉴얼은 위치만 가리킨다.
- 고치는 법·게이트·릴리스는 각 repo의 `docs/work/`다. 이 repo의 매뉴얼은 위치만 가리킨다.
- 템플릿은 `src/settings.gradle`의 `exclusiveContent` 저장소 하나로 받는다: `dev.cakit` group과 그 아래는 소유자 Gitea Packages에서만, 나머지는 Maven Central에서만 찾는다. 공개 owner라 읽기 토큰은 필요 없다. 이미지 빌드(`src/Dockerfile`의 `verifyDependencyLocks`)도 토큰 없이 Gitea에 닿아야 한다.
- 라이브러리 패키지(`dev.cakit.*`)는 템플릿 재사용 체크리스트의 「`dev.caskeleton`을 새 패키지로 바꾼다」에 들지 않는다.
## 2. 라이브러리를 고칠 때
- 템플릿 안에서 라이브러리 코드를 고치지 않는다. 라이브러리 repo에서 고치고 릴리스한다.
- 템플릿 변경 때문에 라이브러리를 고쳐야 하면 브랜치를 둘 만들고, 템플릿에서 명령 줄로만 끼워 같이 시험한다.
- 템플릿 변경 때문에 라이브러리를 고쳐야 하면 두 repo에 브랜치를 하나씩 만들고, 두 repo를 같은 부모 폴더에 둔다(desktop은 `~/workspace/`). 템플릿에서 명령 줄로만 라이브러리를 끼워 같이 시험한다(composite build: Gradle이 같은 `group:artifact`의 외부 의존성을 끼운 빌드의 프로젝트로 바꿔 끼운다). Gradle 루트가 `src/`라 경로는 두 단계 위다.
```bash
./gradlew --include-build ../grpc-library <태스크>
./gradlew --include-build ../../messaging-library <태스크>
```
그 상태로 lockfile을 쓰거나 커밋하지 않는다.
- 병합 순서는 하나다: 라이브러리 PR 병합 → 태그·릴리스 → 템플릿 PR에서 버전을 올리고 lockfile을 다시 쓴다 → 템플릿 병합.
- 라이브러리가 끌고 온 취약 의존성은 템플릿에서 먼저 덮어 막고(Boot 버전이나 카탈로그 `pinned-*`), 라이브러리 repo에 수정을 남긴다.
그 상태로 lockfile을 쓰거나 커밋하지 않는다. 끼운 모듈은 lockfile 밖으로 빠질 수 있다. 끼운 빌드는 자기 카탈로그로 컴파일되므로 라이브러리 repo CI 결과와 다를 수 있다. 최종 판정은 배포한 좌표로 돈 템플릿 게이트다.
- 병합 순서는 하나다: 라이브러리 PR 병합 → 태그·릴리스 → 템플릿 PR에서 버전을 올리고 lockfile을 다시 쓴다 → 템플릿 병합. 끼운 상태로만 통과하는 템플릿 PR은 병합하지 않는다.
- 라이브러리가 끌고 온 취약 의존성은 템플릿에서 먼저 덮어 막고(Boot 버전이나 카탈로그 `pinned-*`. 지금 `pinned-lz4-java`·`pinned-snappy-java`는 메시징 라이브러리의 kafka-clients가 끌고 오는 것을 막는다), 라이브러리 repo에 수정을 남긴다.
## 3. 템플릿이 라이브러리 버전을 올릴 때
라이브러리를 카탈로그로 받는 leaf가 생긴 뒤의 절차다(지금은 없다).
1. `src/gradle/libs.versions.toml`의 라이브러리 버전 칸(`messagingLibrary`)을 바꾼다. 같은 라이브러리의 모듈은 그 칸 하나로 같이 오른다.
2. desktop에서 `./gradlew resolveAndLockAll --write-locks` 뒤 `verifyDependencyLocks`. lockfile 차이는 그 라이브러리 줄과 그것이 끌고 오는 외부 의존성뿐이어야 한다.
3. 쓰는 leaf의 `check`와 `architectureCheck`, 그 leaf의 lane(메시징: `:adapter:inbound:messaging:messagingInboxRedeliveryIntegrationTest`, `:adapter:outbound:messaging-kafka:messagingKafkaRelayIntegrationTest`, persistence-jpa `test`의 migration 시험).
4. 라이브러리 `CHANGELOG.md`에서 그 사이 버전의 깨지는 변경을 읽는다. MAJOR면 `docs/upgrade/`에 행을 더하고 커밋 제목에 `!`. migration을 더한 버전이면 `src/adapter/outbound/persistence-jpa/src/test/resources/db/applied-migrations.sha256`에 줄을 더한다.
5. 커밋 제목 예: `build(deps): 메시징 라이브러리를 1.1.0으로 올린다`.
1. `src/gradle/libs.versions.toml`의 라이브러리 버전 칸을 바꾼다.
2. desktop에서 `./gradlew resolveAndLockAll --write-locks` 뒤 `verifyDependencyLocks`.
3. 쓰는 leaf의 `check`와 `architectureCheck`, 그 leaf의 lane.
4. 라이브러리 `CHANGELOG.md`에서 그 사이 버전의 깨지는 변경을 읽는다. MAJOR면 `docs/upgrade/`에 행을 더하고 커밋 제목에 `!`.
5. 커밋 제목 예: `build(deps): gRPC 라이브러리를 1.1.0으로 올린다`.
## 4. 경계 검사(registry)
## 4. 받는 법(처음 채택할 때)
라이브러리 모듈은 이 빌드의 프로젝트가 아니어서 `allowed_dependencies`가 보지 못한다. 그래서 registry가 두 칸을 더 가진다(`src/config/architecture/README.md` 「별도 repo 라이브러리」).
`src/settings.gradle`의 저장소 선언에 Gitea Maven 저장소를 `exclusiveContent`로 더한다. `dev.cakit` group은 그 저장소에서만, 나머지는 Maven Central에서만 찾는다. 선언 예는 라이브러리 repo README 「받는 법」이다. 공개 owner라 읽기 토큰은 필요 없다.
- 맨 위 `library_groups`(`["dev.cakit"]`): 다스릴 group 접두사.
- 행마다 `allowed_libraries`: 그 leaf가 쓸 수 있는 `group:artifact`. 운영 선언(`runtimeOnly` 포함)과 컴파일에서 보이는 소유 group 모듈이 모두 이 칸에 있어야 방향 검사가 통과한다.
- 새 라이브러리 모듈을 leaf에 들일 때는 카탈로그 항목, leaf `build.gradle`, 그 행의 `allowed_libraries`를 같은 변경에서 바꾼다.
## 5. 처음 채택할 때(gRPC 같은 라이브러리)
`src/settings.gradle`의 저장소 선언은 이미 `dev.cakit`를 덮으니 바꾸지 않는다. 카탈로그에 버전 칸 하나와 쓰는 모듈의 `[libraries]` 항목을 더하고(`version.ref`로 그 칸을 쓴다), 쓰는 leaf의 registry 행에 `allowed_libraries`를 적고, lockfile을 다시 쓴다. 1절 표에 카탈로그 칸과 쓰는 leaf를 적는다.
+4 -4
View File
@@ -101,7 +101,7 @@
| # | 관점 | 볼 곳 | 이런 증거면 결함 |
| --- | --- | --- | --- |
| 1 | 코드 성숙도 | 바뀐 클래스와 호출자, 예외 경로 | 이름·Javadoc과 다른 동작, 항상 참·거짓인 조건 |
| 2 | 구조적 성숙도 | registry `allowed_dependencies`, ArchUnit, leaf `AGENTS.md`, 저장소 루트와 `src/`의 최상위 목록(폴더마다 계층·조립 leaf, Gradle 루트 표준 `build-logic`·`gradle`·`config`, 지도에 적힌 예외 `platforms/`, 저장소 운영 `docs`·`scripts`·`.github` 중 하나인지) | HARD-STOP 위반, registry 밖 leaf 디렉터리, 템플릿 패키지가 기능 패키지를 import, 역할을 한 문장으로 말할 수 없는 최상위 폴더, 같은 역할의 폴더가 같은 높이에 여럿, 지도(`AGENTS.md`)와 `scripts/check-repo-layout.py` 허용 목록에 없는 최상위 항목 |
| 2 | 구조적 성숙도 | registry `allowed_dependencies`, ArchUnit, leaf `AGENTS.md`, 저장소 루트와 `src/`의 최상위 목록(폴더마다 계층·조립 leaf, Gradle 루트 표준 `build-logic`·`gradle`·`config`, 저장소 운영 `docs`·`scripts`·`.github` 중 하나인지) | HARD-STOP 위반, registry 밖 leaf 디렉터리, 템플릿 패키지가 기능 패키지를 import, 역할을 한 문장으로 말할 수 없는 최상위 폴더, 같은 역할의 폴더가 같은 높이에 여럿, 지도(`AGENTS.md`)와 `scripts/check-repo-layout.py` 허용 목록에 없는 최상위 항목 |
| 3 | 변경 용이성 | 기능 하나를 더하거나 뺄 때 고칠 파일, `scripts/new-feature.sh` 왕복 | 같은 규칙을 여러 곳에서 바꿔야 함 |
| 4 | 인지 부하 | 따라 할 예시 수, 같은 질문에 답하는 문서 수, 루트 README만 읽고 구조·매뉴얼·첫 실행을 5분 안에 찾는가(cold-read 결과), 이벤트별 workflow job 수 | 예시·규칙이 여러 갈래이고 고르는 기준이 없음, 같은 Gradle 태스크를 두 단계 이상이 돎(의도한 행렬 제외) |
| 5 | 위험 가시성 | 기본값, 설정 검증, 기동 rule, 프로필 허용 목록 | 위험이 기본값 뒤에 숨음, 레지스트리 `required`인데 코드는 빈 값 허용 |
@@ -201,15 +201,15 @@ RED가 증거가 되려면: 실패 메시지가 그 결함을 말한다. 머신
- 새 업무 기능은 계층 leaf 안의 패키지가 기본이다(`docs/manual/03-placement.md`).
- 템플릿 패키지 목록은 `src/application-core/README.md` 「패키지 소유 (Package ownership)」 표 하나가 정본이다. 템플릿에 패키지를 더하면 같은 변경에서 표에 넣는다.
- capability는 자기 `AutoConfiguration.imports`로 켜진다. `app-bootstrap`은 capability 이름·스위치 목록·scan 정규식을 갖지 않는다.
- 다른 경계(다른 leaf, 다른 빌드, 다른 repo가 될 수 있는 폴더)의 파일을 경로(`../../../`)로 읽는 빌드 스크립트·테스트는 결함 후보다. 그 경계가 옮겨 가면 조용히 깨진다. gRPC 라이브러리를 옮길 때 이런 결합이 다섯 곳 나왔다(design-docs `repo-structure/05-library-repos.md` 4.6절).
- vendored family(`messaging:*`)는 `domain-core`·`application-core`·`shared-contract`에 의존하지 않는다. 그래서 남는 복사본은 이유를 family `AGENTS.md`에 적고, 값이 같아야 하면 대조 테스트를 둔다.
- 다른 경계(다른 leaf, 다른 빌드, 다른 repo가 될 수 있는 폴더)의 파일을 경로(`../../../`)로 읽는 빌드 스크립트·테스트는 결함 후보다. 그 경계가 옮겨 가면 조용히 깨진다. gRPC·메시징 라이브러리를 옮길 때 이런 결합이 다섯 곳 나왔다(design-docs `repo-structure/05-library-repos.md` 4.6절). 다른 repo의 파일이 필요하면 그 repo가 배포한 artifact에서 읽는다(예: persistence-jpa의 migration 시험이 메시징 라이브러리 jar의 `db/migration/messaging`을 푼다).
- 별도 repo 라이브러리(`dev.cakit.*`)는 템플릿 타입에 의존하지 않는다. 그래서 남는 복사본은 이유를 그 라이브러리 repo의 모듈 지침에 적는다. 템플릿 leaf가 라이브러리 모듈을 쓰면 registry 행의 `allowed_libraries`에 좌표를 적는다. 적지 않은 소유 group 모듈을 선언하거나 컴파일에서 보면 방향 검사가 실패한다.
- source set은 runtime·classpath·외부 인프라·JVM 옵션·실행 비용 중 하나가 다를 때만 나눈다. 공유 테스트 코드는 `src/testFixtures/java`다(`docs/adr/ADR-BUILD-001-one-convention-for-shared-test-code.md`).
- 마이그레이션은 저장소마다 자기 디렉터리와 history table을 가진다. 번호는 스트림 안의 순번이다. 어딘가에 적용된 파일은 고치지 않는다(`src/adapter/outbound/persistence-jpa/src/test/resources/db/applied-migrations.sha256`이 해시를 고정한다).
- 문서 위치 규칙은 `docs/README.md`가 정본이다.
leaf를 더하거나 옮기거나 지울 때 같은 변경에서 함께 바꾼다:
- [ ] `src/config/architecture/modules.json`: ID, `source_path`, `gradle_path`, `allowed_dependencies`
- [ ] `src/config/architecture/modules.json`: ID, `source_path`, `gradle_path`, `allowed_dependencies`, 라이브러리를 쓰면 `allowed_libraries`
- [ ] leaf `build.gradle`: `ca.java-library`·`ca.spring-library`·`ca.platform-module` 중 하나
- [ ] lockfile(`verifyDependencyLocks`가 통과하게 다시 만든다)
- [ ] capability면 `src/app-bootstrap/build.gradle`의 `runtimeOnly` 한 줄과 자기 `AutoConfiguration.imports`
+2 -2
View File
@@ -2,7 +2,7 @@
- 모듈 ID `adapter-inbound-messaging`, Gradle 경로 `:adapter:inbound:messaging`. registry 정본:
`src/config/architecture/modules.json`.
- 책임: 들여온 메시징 플랫폼의 애플리케이션 소비 쪽이다 — 플랫폼이 애플리케이션에서 받아야 하는
- 책임: 메시징 라이브러리(별도 repo messaging-library, Maven `dev.cakit.messaging`)의 애플리케이션 소비 쪽이다 — 라이브러리가 애플리케이션에서 받아야 하는
inbox 부품(애플리케이션 DataSource 위의 `JdbcInboxRepository`, 그 `PlatformTransactionManager` 위의
`TransactionRunner`, 자기 Flyway stream `MessagingInboxSchemaStream`인 inbox migration)과 애플리케이션의
`MessageHandler` 구현들이다. 핸들러 하나는 전달 하나를 유스케이스 호출 하나로 바꾼다. 핸들러는 그 밖에
@@ -14,7 +14,7 @@
(`docs/manual/09-outbox-events.md` 「소비 — 이벤트를 받는 쪽」 순서 4단계,
`docs/manual/07-authorization.md` 「시스템이 부르는 쓰기」,
`ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`, `SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS`,
`USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`). 핸들러는 프로젝트 타입(`MessageHandler<T>`)만 구현하고,
`USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`). 핸들러는 프로젝트 타입(메시징 라이브러리의 `MessageHandler<T>`. `dev.cakit..`도 프로젝트 타입으로 친다)만 구현하고,
`Runnable`이나 프로젝트 밖의 다른 타입은 구현하지 않는다(`SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES`).
- 시험: 자동 구성과 inbox 동작을 보는 시험. `./gradlew :adapter:inbound:messaging:check`.
실제 Kafka + PostgreSQL 재전달 lane은 `messagingInboxRedeliveryIntegrationTest`다(`:integrationCheck`).
@@ -3,10 +3,11 @@
- 모듈 ID `adapter-outbound-messaging-kafka`, Gradle 경로 `:adapter:outbound:messaging-kafka`.
registry 정본: `src/config/architecture/modules.json`.
- 책임: Kafka 발행 capability를 `runtimeOnly` 한 줄로 만든다. 운영 코드가 없다:
`adapter:outbound:messaging`(애플리케이션의 bridge)과 `messaging:messaging-spring-boot-starter-kafka`(들여온
플랫폼과 그 Kafka 전송)를 묶고, 모듈 기본값 `config/module-defaults/messaging.yml`을 싣는다.
- 경계: 여기 코드를 더하지 않는다. 발행 규칙은 bridge(`adapter:outbound:messaging`)에, Kafka 규칙은 들여온
제품(`src/platforms/messaging/AGENTS.md`)에 속한다. 여기 클래스를 두면 세 번째 자리가 생긴다. 허용 edge는
`adapter:outbound:messaging`(애플리케이션의 bridge)과 메시징 라이브러리의 `messaging-spring-boot-starter-kafka`(Kafka
전송, Maven `dev.cakit.messaging`, 카탈로그 `libs.messaging.spring.boot.starter.kafka`)를 묶고, 모듈 기본값
`config/module-defaults/messaging.yml`을 싣는다.
- 경계: 여기 코드를 더하지 않는다. 발행 규칙은 bridge(`adapter:outbound:messaging`)에, Kafka 규칙은 메시징
라이브러리(messaging-library repo의 [messaging/AGENTS.md](https://git.learn.hyeonworks.com/donghyeon.kang/messaging-library/src/branch/main/messaging/AGENTS.md))에 속한다. 여기 클래스를 두면 세 번째 자리가 생긴다. 허용 edge는
registry 항목에서만 온다.
- 시험: 켜기 시험(`./gradlew :adapter:outbound:messaging-kafka:test`)과 실제 Kafka lane
`messagingKafkaRelayIntegrationTest`(relay → bridge → broker record 바이트, `:integrationCheck`).
+10 -8
View File
@@ -15,7 +15,8 @@ adapter:outbound:messaging-kafka
├─ config/module-defaults/messaging.yml (설정 기본값, support 로더가 읽음)
├─ adapter:outbound:messaging OutboxMessagePublishPort,
│ IntegrationEventPublishPort bridge
└─ messaging:messaging-spring-boot-starter-kafka messaging platform + Kafka transport
└─ dev.cakit.messaging:messaging-spring-boot-starter-kafka 메시징 라이브러리 + Kafka transport
(별도 repo messaging-library, 카탈로그 messagingLibrary)
```
| 포트 (application-core) | 구현 |
@@ -31,7 +32,8 @@ adapter:outbound:messaging-kafka
app-bootstrap은 이 파일을 모른다.
- broker 주소는 `APP_MESSAGING_KAFKA_BROKERS` 하나(`app.messaging.brokers.kafka.bootstrap-servers`).
`spring.kafka.bootstrap-servers`는 읽지 않는다. 논리 broker 이름은 `kafka` 하나다. Kafka 연결의
TLS·SASL은 platform의 broker profile이 소유한다(`docs/messaging/configuration-reference.md`).
TLS·SASL은 메시징 라이브러리의 broker profile이 소유한다(그 repo의
[configuration-reference.md](https://git.learn.hyeonworks.com/donghyeon.kang/messaging-library/src/branch/main/docs/messaging/configuration-reference.md)).
- 발행 경로는 하나다. 옛 `KafkaSender` seam(TLS/SASL 없는 R0 producer)은 outbox를 canonical로
통일하면서 삭제했다(2026-09-28).
- 발행할 event의 contract마다 destination을 선언해야 한다(`app.messaging.destinations.<logical
@@ -44,7 +46,7 @@ adapter:outbound:messaging-kafka
runtimeOnly project(':adapter:outbound:messaging-kafka') // Kafka 발행
```
이 줄을 지우면 발행 포트 구현, Kafka client, messaging platform, 설정 기본값이 모두 함께 빠진다.
이 줄을 지우면 발행 포트 구현, Kafka client, 메시징 라이브러리, 설정 기본값이 모두 함께 빠진다.
## 필요한 env 키
@@ -56,16 +58,16 @@ runtimeOnly project(':adapter:outbound:messaging-kafka') // Kafka 발행
| 항상 | `APP_MESSAGING_PRODUCER_ID` (배포와 무관한 논리적 서비스 이름). 비어 있으면 기동이 실패한다 — 모든 발행이 canonical bridge를 지난다 |
| 끌 때 | `APP_MESSAGING_ENABLED=false` |
`APP_MESSAGING_BROKER`는 platform이 쓸 broker 선택값이고 기본값이 `kafka`다. 등록된 broker가 Kafka
하나라 바꿀 일이 없다. destination·broker profile·보안 설정은
`docs/messaging/configuration-reference.md`.
`APP_MESSAGING_BROKER`는 메시징 라이브러리가 쓸 broker 선택값이고 기본값이 `kafka`다. 등록된 broker가 Kafka
하나라 바꿀 일이 없다. destination·broker profile·보안 설정은 messaging-library repo의
[configuration-reference.md](https://git.learn.hyeonworks.com/donghyeon.kang/messaging-library/src/branch/main/docs/messaging/configuration-reference.md)다.
## 실제 broker로 도는 앱 발행 경로 lane (`messagingKafkaRelayIntegrationTest`)
앱이 실제로 쓰는 발행 경로 — `composition:outbox-relay` relay → `OutboxMessagePublishAdapter` →
platform bridge → `DefaultMessagePublisher` → Kafka — 를 Testcontainers Kafka(`apache/kafka:4.1.0`,
`-PmessagingKafkaImage=`로 교체)로 끝까지 돌린다(리뷰 2026-11-01 06-09). vendored 쪽 broker lane은
platform 자기 relay와 publisher 직접 호출만 검증하므로 앱 경로의 증거가 아니다.
`-PmessagingKafkaImage=`로 교체)로 끝까지 돌린다(리뷰 2026-11-01 06-09). 메시징 라이브러리 쪽 broker lane
(그 repo의 인증 lane)은 라이브러리 자기 relay와 publisher 직접 호출만 검증하므로 앱 경로의 증거가 아니다.
- 정상 발행: append한 row를 relay가 보내고, 테스트가 topic에서 읽은 레코드 값이 envelope 바이트와
같고 key가 partition key와 같다.
@@ -111,6 +111,7 @@ lock TTL)과 계약 표(트랜잭션 모드, SQLState → 오류 코드, vendor,
- `:shared-contract`
- `:adapter:outbound:support`(타입 있는 기동 실패, EnvironmentPostProcessor 순서, readiness group, module-defaults 읽기)
- Spring Data JPA와 Spring transaction.
- 시험만: 메시징 라이브러리 jar(`dev.cakit.messaging:messaging-reliability-jdbc-postgresql`)를 전용 구성 `messagingMigrations`로 받아 그 `db/migration` 트리를 푼다. migration 시험(`MigrationTrees`)이 같은 Flyway 이력에 들어가는 메시징 migration을 이 leaf의 것과 같은 규칙으로 보기 위해서다. 어떤 classpath에도 올리지 않으므로 registry 방향 검사(운영 구성만 본다) 밖이다. 다른 repo의 파일을 경로로 읽지 않는다.
## 금지 (Forbidden)
+1 -1
View File
@@ -4,7 +4,7 @@ registry, settings, build-logic, 루트 라이프사이클이 정하는 것을
## 정본 넷
- `src/config/architecture/modules.json`: 등록된 모든 leaf의 ID, repository-relative 소스 경로, Gradle path, 허용 production project dependency edge. runtime membership 목록은 없다. 조립 루트가 받을 수 있는 모듈은 `allowed_dependencies`가 정하고, 방향 게이트가 그 밖의 edge를 막는다. leaf 목록과 그 개수의 정본은 registry다. 문서는 개수를 적지 않는다. 산문에 적힌 숫자는 leaf가 더해지는 순간 틀린다. 그 숫자를 강제하던 태스크(`verifyDocumentedLeafCount`)는 지웠다. 문서에 적힌 수가 틀린 것은 결함이지만 빌드를 실패시킬 사유는 아니고, 그 태스크는 모든 지역 문서와 `build.gradle`을 정규식으로 훑는 파서였다.
- `src/config/architecture/modules.json`: 등록된 모든 leaf의 ID, repository-relative 소스 경로, Gradle path, 허용 production project dependency edge, 그리고 별도 repo 라이브러리 edge(맨 위 `library_groups`, 행마다 `allowed_libraries`. 계층 leaf 행은 비워 둔다. 설명은 `src/config/architecture/README.md`). runtime membership 목록은 없다. 조립 루트가 받을 수 있는 모듈은 `allowed_dependencies`가 정하고, 방향 게이트가 그 밖의 edge를 막는다. leaf 목록과 그 개수의 정본은 registry다. 문서는 개수를 적지 않는다. 산문에 적힌 숫자는 leaf가 더해지는 순간 틀린다. 그 숫자를 강제하던 태스크(`verifyDocumentedLeafCount`)는 지웠다. 문서에 적힌 수가 틀린 것은 결함이지만 빌드를 실패시킬 사유는 아니고, 그 태스크는 모든 지역 문서와 `build.gradle`을 정규식으로 훑는 파서였다.
- `src/settings.gradle`: `ca.architecture-registry` 설정 플러그인이 registry를 읽어 project를 include·mapping한다. registry가 project 목록이 될 수 없는 경우(중복 ID, 저장소 밖 경로, 없는 디렉터리)만 여기서 실패한다. 허용되지 않는 edge 같은 아키텍처 규칙은 `verifyCleanArchitectureDependencies`가 답한다. settings에서 죽으면 실행할 수 있는 태스크가 하나도 없다.
- `src/build-logic/`: 아키텍처 코어(registry, 방향·순수성 task), 컨벤션, 테스트 레인 하나(`strictTestLanes`). leaf는 `ca.java-library`·`ca.spring-library`·`ca.platform-module` 중 자기 성격을 선언하고, 그 플러그인이 toolchain·락·정적분석·테스트 기본값을 준다. `ca.architecture`가 아키텍처 검증 태스크를 가진다. 기능별 검사(notification·mongo·messaging·graphql·JPA readiness 등)는 build-logic이 아니라 그 leaf의 테스트다.
- `src/build.gradle`: 루트 라이프사이클(`ci`, `mainCheck`, `integrationCheck`, `performanceCheck`, `releaseCheck`, `qualityCheck`, `configContractCheck`)과 버전·리비전.
File diff suppressed because one or more lines are too long
+19 -1
View File
@@ -4,7 +4,7 @@
프로젝트 edge를 정확히 적는다. 빈 `allowed_dependencies` 목록에도 뜻이 있다: 그 leaf가 일부러 다른
프로젝트에 기대지 않는다는 뜻이지, registry 항목을 덜 채웠다는 뜻이 아니다.
`domain-core`, `shared-contract`, 들여온 메시징 제품의 `messaging-core-api`가 그 예다. 빈 목록은
`domain-core`, `shared-contract`가 그 예다. 빈 목록은
분명한 경계이고, 실제 프로젝트 edge를 들여와 리뷰하기 전까지 비어 있어야 한다. 반대로 목록에 적힌
edge는 빌드가 실제로 쓰는 것과 맞아야 한다. 예를 들어 `adapter-outbound-persistence-mongo`의 목록은
`["application-core", "shared-contract"]`이고 `MongoRegistryPermissionParityTest`가 두 방향을 모두
@@ -12,3 +12,21 @@ edge는 빌드가 실제로 쓰는 것과 맞아야 한다. 예를 들어 `adapt
런타임 조립 구성원은 빌드 로직이 해석된 runtime classpath에서 얻는다. 이 registry에 모듈마다 칸으로
다시 적지 않는다.
## 별도 repo 라이브러리: `library_groups`와 `allowed_libraries`
소유자가 다른 repo에서 배포하는 라이브러리(메시징 `dev.cakit.messaging`, gRPC `dev.cakit.grpc`)는 이 빌드의
프로젝트가 아니라 외부 좌표다. 그래서 프로젝트 edge 규칙(`allowed_dependencies`)이 보지 못한다. 그 빈자리를
두 칸이 메운다(설계 design-docs `repo-structure/05-library-repos.md` 10.2절 T2, 소유자 승인 2026-11-07).
- 맨 위 `library_groups`: 다스릴 라이브러리의 Maven group 접두사. 지금 `["dev.cakit"]`이다. 이 접두사와
같거나 그 아래(`dev.cakit.` 다음) group만 다스린다. 다른 group(Spring, Kafka client 등)은 이 칸과 상관없다.
- 행마다 선택 칸 `allowed_libraries`: 그 leaf가 쓸 수 있는 라이브러리 모듈의 `group:artifact` 목록. 없으면 빈
목록과 같다. 값은 `library_groups` 안의 group이어야 하고 겹치면 안 된다(registry를 읽을 때 거절).
- 방향 검사(`verifyModuleDependencyDirection`, `verifyCleanArchitectureDependencies` 아래)는 프로젝트 edge와 같은
방식으로 대조한다: 운영 선언(`api`·`implementation`·`compileOnly`·`runtimeOnly`)의 소유 group 좌표와,
`compileClasspath`에서 보이는 소유 group 모듈(라이브러리 모듈이 `api`로 내보낸 것 포함)이 모두 칸에 있어야
한다. 시험 구성은 보지 않는다.
- 그래서 지금 지키는 약속 셋이 검사로 남는다: bridge(`adapter-outbound-messaging`)는 `messaging-core-api`만 본다.
Kafka capability(`adapter-outbound-messaging-kafka`)는 starter-kafka를 `runtimeOnly`로만 싣는다. 계층 leaf는
칸이 비어 있으니 라이브러리를 쓸 수 없다.
+1 -1
View File
@@ -27,7 +27,7 @@ tracing 이음매, domain-context 전파)은 [README.md](README.md)에 있다.
- 모든 leaf가 복사해 쓰던 표준 라이브러리 도우미(2026-09-25 리뷰 후속으로 여기로 옮겼다):
`digest/Sha256`(SHA-256 digest 값과 유일한 `MessageDigest.getInstance("SHA-256")`),
`digest/HmacSha256`(서명과 상수 시간 검증), `retry/Backoff`(상한 있는 지수 ceiling. "full jitter"는
`U[0, ceiling]`이고 다른 뜻이 아니다). 들여온 `messaging:*`와 별도 repo 라이브러리(grpc-library)는 이 모듈에
`U[0, ceiling]`이고 다른 뜻이 아니다). 별도 repo 라이브러리(messaging-library, grpc-library)는 이 모듈에
의존하지 않고 자기 사본을 둔다. 각 제품의 AGENTS.md(라이브러리는 그 repo)가 이유를 적는다(다른 제품이다.
2026-08-14 메시징 모듈 리뷰 뒤에 정했다). 이 도우미가 필요한 템플릿 leaf는 모두 `shared-contract` edge를 두고 복사하지
않고 쓴다. identifier, persistence-mongo, application-objectstorage, redis-sdk가 바로 이 때문에