diff --git a/AGENTS.md b/AGENTS.md index 9290967..c642f01 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,36 +1,38 @@ # AGENTS.md — messaging-library의 정본 -템플릿 밖에서 버전으로 배포하는 브로커 중립 메시징 라이브러리(dev.cakit.messaging) 방향은 `docs/vision.md`, 풀 문제와 하지 않을 것은 `docs/problem-statement.md`다. +Spring Boot 앱에 브로커 중립 메시징(발행·소비, outbox·inbox, 재시도·DLQ, 브로커 인증 증거)을 붙이는 라이브러리다(Maven group `dev.cakit.messaging`). 백엔드 템플릿에서 2026-11-08에 이력째 옮겨 왔다. 왜 따로 두는지와 받는 법은 `README.md`, 풀 문제는 `docs/problem-statement.md`다. ## 꼭 지킬 것 — 하나라도 어기면 동작해도 완료가 아니다 1. 관련 검증(아래 「검증」) 없이, 또는 돌리지 못한 이유를 밝히지 않고 완료를 말한다. 2. 요청 범위 밖의 큰 리팩터링, 사용자 변경 되돌리기, 요청 없는 파괴적 명령을 한다. -3. 비밀 값(`.env`, 키, 토큰)을 읽거나 커밋한다. -4. (채울 것: 이 프로젝트의 아키텍처 불변식. 예: 도메인 계층이 프레임워크·DB를 import한다) +3. 비밀 값(`.env`, 키, 토큰)을 읽거나 커밋한다. 배포 토큰·서명 키는 repo secret에만 있다. +4. `*-api` 모듈(`messaging-core-api`, `-policy`, `-reliability-api`, `-transport-spi`)이 Java 표준 라이브러리 밖 타입을 쓰거나, Spring이 조립 경계(`*-spring-boot-starter*`, `reliability-jdbc-postgresql`) 밖으로 나간다. 표는 `messaging/AGENTS.md`. +5. 백엔드 템플릿의 타입이나 파일 경로에 기댄다. 필요하면 edge 없는 복사본을 두고 이유를 적는다. +6. 배포한 버전을 지우거나 같은 버전을 다시 올린다. 적용된 migration(`db/migration/messaging/V*.sql`)의 내용이나 위치를 바꾼다. +7. 공개 타입·설정 키(`app.messaging.*`)를 바꾸면서 버전 규칙(`docs/work/release.md` 2절)을 따르지 않는다. 인증 manifest를 손으로 고친다. ## 지도 -- (채울 것: 최상위 폴더 → 하는 일. 개수·버전 숫자는 적지 않는다. 정본이 따로 있으면 그 파일을 가리킨다) -- 폴더마다의 규칙은 그 폴더의 `AGENTS.md`다. 작업 파일과 가장 가까운 것을 따른다. -- 결정 기록은 `docs/adr/`(양식 `0000-template.md`), 예측·실측 장부는 `docs/ledger/`다. +- `messaging/`: 모듈. 모듈 목록·경로·허용 의존의 정본은 registry `config/architecture/modules.json`이다. 개수는 적지 않는다. family 규칙은 `messaging/AGENTS.md`. +- `build-logic/`: 템플릿에서 복사해 줄인 convention 플러그인. 출처와 고친 것은 `build-logic/UPSTREAM.md`. +- `build.gradle`: 단계 태스크(`ci`·`mainCheck`·`releaseCheck`·`release`). `.gitea/workflows/`는 단계마다 Gradle 한 줄이다. +- `scripts/`: 고정 도구(`tool.sh`), 릴리스 보조(`release/`), 검증 진입점(`verify.sh`). +- 살아 있는 제품 문서는 `docs/messaging/`, 설계 기록은 `docs/design/`, 장부는 `docs/ledger/`. 지도는 `docs/README.md`. ## 맡은 일 -- (채울 것: 일의 종류 → 먼저 읽을 문서. 예: 새 기능 → `docs/…`) +- 고치기·리뷰 → `docs/work/README.md`, 게이트 고르기 → `docs/work/gates.md`, 릴리스 → `docs/work/release.md`. +- 템플릿과 같이 고치기(composite build), 소비자 영향 확인 → `docs/work/README.md` 3절. - brief가 있으면 brief의 범위·크기·완료 기준이 먼저다. ## 검증 -- 진입점은 하나다: `scripts/verify.sh <단계>`(docs · unit · pr · app). 사람·CI·에이전트가 같은 명령을 쓴다. -- 무거운 실행을 다른 기계에서 돌릴 때는 `scripts/verify.sh <단계> --on <호스트>`(지금 작업 트리를 패치로 옮긴다). - -## 헷갈리는 곳 - -- (채울 것: 코드만 보고는 알 수 없는 것. 없으면 이 절을 지운다) +- 진입점: `scripts/verify.sh <단계>`(docs · unit · pr · main · release). 사람·CI·에이전트가 같은 명령을 쓴다. +- Gradle·Docker는 소유자 환경에서 desktop에서만 돈다: `scripts/verify.sh pr --on desktop`. ## 일하는 방식 -- 착수할 때 예측을, 끝날 때 실측을 장부에 남긴다(Claude Code는 `estimate` 스킬). -- 파일을 바꾸는 위임은 사람이 열어 보고 멈출 수 있는 하위 세션에, 결과만 받는 일(검색·구조 리뷰·실행 검증)은 서브에이전트에 맡긴다. -- 커밋 메시지·PR 규칙: (채울 것: 규칙 문서 경로) +- 착수할 때 예측을, 끝날 때 실측을 `docs/ledger/estimates.jsonl`에 남긴다(Claude Code는 `estimate` 스킬). +- 파일을 바꾸는 위임은 하위 세션에, 결과만 받는 일은 서브에이전트에 맡긴다. +- 커밋·PR 규칙: design-docs `conventions/commit-and-pr.md`(PR 본문 칸은 `.gitea/pull_request_template.md`). diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..3b1ba16 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,16 @@ +# 바뀐 것 + +버전마다 바뀐 것과, 깨지는 변경이면 옮기는 법을 쓴다. 버전 규칙은 `docs/work/release.md` 2절이다. + +## 1.0.0 — 아직 내지 않음 + +백엔드 템플릿 안에 있던 메시징 플랫폼(`src/platforms/messaging`)의 첫 배포 버전이다. 동작은 템플릿 main `2959eff0`의 그 코드와 같다. + +### 템플릿 안에서 쓰던 코드에서 옮기는 법 + +템플릿 안 코드를 직접 썼다면(템플릿 기준 커밋 `2959eff0` 이전): + +- Java 패키지: `dev.caskeleton.messaging.*` → `dev.cakit.messaging.*`. import를 바꾼다. 템플릿 재사용 체크리스트의 `dev.caskeleton` 일괄 바꾸기와 겹치지 않게 다른 이름을 쓴다. +- Kafka 클라이언트 설정 키 `caskeleton.messaging.credential.registry`·`.id` → `cakit.messaging.credential.registry`·`.id`. 라이브러리가 스스로 넣고 읽는 키라, 상수(`KafkaCredentialCallbackHandler.REGISTRY`·`CREDENTIAL_ID`)를 쓴 코드는 바꿀 것이 없다. +- Gradle: `project(':messaging:<모듈>')` → `dev.cakit.messaging:<모듈>:1.0.0`(저장소 선언은 README 「받는 법」). +- 그대로인 것: 설정 키 `app.messaging.*`, Flyway 위치 `db/migration/messaging`과 migration 파일(`V1001`~`V1005`, `V1101`), 표 이름(`messaging_outbox`, `messaging_inbox`, admin journal), Spring auto-configuration 등록. diff --git a/CLAUDE.md b/CLAUDE.md index cbbd698..f0e7062 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -3,5 +3,15 @@ ## Claude Code에서만 - 권한은 `.claude/settings.json`이다: 실제 `.env` 읽기·쓰기를 막는다(`.env.example` 같은 예시는 막지 않는다). -- 공통 훅과 스킬은 하네스 플러그인 `harness@claude-harness`가 준다: 되돌릴 수 없는 명령 차단, 비밀 값 알림, 예측·실측 장부 기록, `estimate`·`retro`·`techdebt`. 플러그인 설명은 claude-harness repo의 README다. -- 이 프로젝트만의 훅은 `scripts/hooks/`, 경로별 규칙은 `.claude/rules/`, 스킬은 `.claude/skills/`, 서브에이전트는 `.claude/agents/`에 둔다. +- 공통 훅과 스킬은 하네스 플러그인 `harness@claude-harness`가 준다: 되돌릴 수 없는 명령 차단, 비밀 값 알림, 예측·실측 장부 기록, `estimate`·`retro`·`techdebt`. 대화형 Claude Code는 이 폴더를 처음 믿을 때 설치를 묻는다. 비대화형(`claude -p`)은 묻지도 설치하지도 않으니 이 폴더에서 한 번 돌린다(설정 파일은 이미 맞다). + + ```bash + claude plugin marketplace add https://git.learn.hyeonworks.com/donghyeon.kang/claude-harness.git --scope project + ``` + + ```bash + claude plugin install harness@claude-harness --scope project + ``` + +- 이 repo만의 훅·경로 규칙·스킬·서브에이전트는 아직 없다. 생기면 `scripts/hooks/`, `.claude/rules/`, `.claude/skills/`, `.claude/agents/`에 둔다. +- 소유자 환경: Gradle·Docker는 desktop에서만 돈다. `scripts/verify.sh <단계> --on desktop`(무거운 실행은 `/tmp/claude-gates/heavy.lock` 아래). diff --git a/README.md b/README.md new file mode 100644 index 0000000..bec1eb0 --- /dev/null +++ b/README.md @@ -0,0 +1,114 @@ +# messaging-library + +Spring Boot 앱에 브로커 중립 메시징을 붙이는 라이브러리다. 발행·소비 API와 transport SPI, Kafka adapter, 관계형 outbox·inbox(PostgreSQL)와 relay, 재시도·DLQ·redrive 정책, 보안·관측 규칙, schema codec(JSON·Avro·Protobuf·CloudEvents), 운영자 admin 계약, 실제 브로커로 만든 인증 증거를 준다. + +```text +앱 소유 port ──> 앱의 adapter(bridge) ──> messaging-core-api (Java 표준 라이브러리만: envelope·destination·publish 결과·port) + └─ messaging-spring-boot-starter (조립, broker 중립) + ├─ messaging-runtime-core (중앙 publish 경로) + ├─ messaging-reliability (+ -api, -jdbc-postgresql): outbox·inbox + ├─ messaging-policy · -security · -observability · -admin + └─ messaging-spring-boot-starter-kafka (Kafka transport capability) +``` + +## 받는 법 + +Maven group은 `dev.cakit.messaging`, artifact는 모듈 이름 그대로다(`messaging-core-api`, `messaging-spring-boot-starter-kafka`, …). 저장소는 소유자 Gitea Packages이고, 공개라 읽을 때 토큰이 필요 없다. + +```groovy +// settings.gradle +dependencyResolutionManagement { + repositories { + exclusiveContent { + forRepository { + maven { url = 'https://git.learn.hyeonworks.com/api/packages/donghyeon.kang/maven' } + } + filter { includeGroupByRegex 'dev\\.cakit(\\..*)?' } + } + mavenCentral() + } +} +``` + +```groovy +// build.gradle +dependencies { + implementation 'dev.cakit.messaging:messaging-core-api:1.0.0' + runtimeOnly 'dev.cakit.messaging:messaging-spring-boot-starter-kafka:1.0.0' +} +``` + +`exclusiveContent`는 `dev.cakit` group을 이 저장소에서만, 나머지는 Maven Central에서만 찾게 한다. 같은 이름을 공개 저장소에 올리는 공격이 통하지 않고, Gitea가 느려도 다른 의존성 해석에는 영향이 없다. + +신뢰성 migration은 `messaging-reliability-jdbc-postgresql` jar 안의 classpath 위치 `db/migration/messaging`(`V1001`~`V1005` outbox·admin journal, `V1101` inbox)에 있다. 받는 앱의 Flyway가 그 위치를 읽게 한다. 이 위치와 파일 내용은 배포한 뒤 바꾸지 않는다. + +## 지원 표 + +| 라이브러리 | Spring Boot(컴파일·시험한 줄) | Kafka client · 인증한 broker | PostgreSQL(시험) | Java | +| --- | --- | --- | --- | --- | +| 1.0.x | 4.0.x (`4.0.9`) | `kafka-clients` 4.1.2(Boot가 관리) · `apache/kafka:4.1.0` | 16 | 21 | + +무엇을 인증했고 무엇은 지켜보기만 하는지는 `docs/messaging/support-matrix.md`다. 인증 증거는 `messaging/messaging-testkit/src/main/resources/messaging/broker-certification-evidence.jsonl`이고, main 단계가 실제 Kafka로 다시 만들어 대조한다. + +## 프로젝트 구조 + +| 폴더 | 무엇 | +| --- | --- | +| `messaging/` | 모듈. 규칙은 `messaging/AGENTS.md` | +| `build-logic/` | 백엔드 템플릿에서 복사해 줄인 Gradle convention 플러그인. 출처는 `build-logic/UPSTREAM.md` | +| `config/` | 모듈 registry(`architecture/modules.json`), Checkstyle·SpotBugs 설정, 테스트 컨테이너 이미지 | +| `scripts/` | 검증 진입점 `verify.sh`, 고정 도구 `tool.sh`, 릴리스 보조 `release/` | +| `.gitea/workflows/` | 단계 파일: `pr.yml`(`ci`), `main.yml`(`mainCheck`), `release.yml`(`releaseCheck release`), `signing-check.yml`(수동) | +| `docs/` | 문서. 지도는 `docs/README.md` | + +## 문서 지도 + +- 작업 방법: `docs/work/README.md`(고치기·리뷰), `docs/work/gates.md`(게이트), `docs/work/release.md`(릴리스·버전 규칙·비밀 값) +- 제품 문서: `docs/messaging/`(설정 참조, 전달 보장, outbox·inbox, 재시도·DLQ·redrive, 보안, 운영, 지원 표, 실험 정책, 이전·cutover 안내) +- 설계서: `docs/design/2026-08-10-messaging-platform-design.md` +- 바뀐 것: `CHANGELOG.md` + +## 서명 + +배포 파일마다 PGP 서명(`.asc`)이 붙는다. 서명 키는 RSA 4096, 지문 `92646CEAFE816CF8B9C249F0A1C936D7F791F8AB`, 2028-11-07에 만료된다. grpc-library와 같은 키다. 키를 바꾸는 법은 `docs/work/release.md` 1절이다. + +```text +-----BEGIN PGP PUBLIC KEY BLOCK----- + +mQINBGrv1SYBEADGgq8CTE7wdDPIg0zNRXelPvlgyK04tpDTL0b9k1INxDwFEiS0 +87bTL22Zjipp+2uDg012TALeLsDV12yh1IToNaYq7zR9bRvEua25+351zw91ojC+ +z2/1Y7S98o813hu6qP6EFUHnsWPVLEt40mlGDn3kl8iXMLgjozVYbylomweh/Yvz +HLJd5lQGE76mIejIeGp3m1OA5M2RV4xspA8K8TZkXXSqe3nbfSjPXAOwysPmRRd9 +IoLDwakSq4tRI9dlm08bzznsoaaTCRcJ0XAbJK7+ZrQkSwIrsi/gsBkCOJI6Wcs6 ++R+9Wy7tYsyd59TdgIdjq3uHadSLWQ3dc0g0ux2krxSL0PHXrT9Upmcorj2+Ltkh +9J1I6hUv1O7e0Y8Es7Ov5WUPfdSdQ5ApwtwFX5aSwYokoW9wXMLg2zdQx0JEx1ix +/qTEvpSKfM0/zVbKJO9RDF/F7HZkDWSOhZe+4x7dak+xN6KOfEQVmcBneaGtPqgJ +eAsIBgRwp42G5llqnTcWAHLAKCDEE9wHK3+gJt5f5rO5e+r1GoYHLn0Iw3iiX6rC +NFot/5my/oePTeRur5tjv14kw1FMXHVNvLOxHeaiZzfVVjO/vbwAtGvZDiRdAgd6 +kHyt9Ch/JccIa0ylA9Tttb0A33ZGTQl6sAC6jTSIhfnEAdlCX7MVAE8n4wARAQAB +tCNkb25naHllb24ua2FuZyA8ZG9uZzUxMjlAZ21haWwuY29tPokCVwQTAQoAQRYh +BJJkbOr+gWz4ucJJ8KHJNtf3kfirBQJq79UmAhsDBQkDwmcABQsJCAcCAiICBhUK +CQgLAgQWAgMBAh4HAheAAAoJEKHJNtf3kfir2j8P/RWRT0GTxBNQvm76iO6XnvFD +mDPGq37A5iuD4pJ624/BccKTGe8+WWqtlpAiN6AdHGNi/LGhuYaGL9ce6Gja5tTX +y/ZY8jthbEoi41g6cim8W8knd3v2Ne/qj3dKvphSiVsZBrumEzrZyw2UUD3IRqVx +r2WQZTcSa4UDd7+Qie0h8IrnmfMYIseDCWjDCATNJqr9PBGoKYehv8+Wo3QDVBRd +B0lWepudJjLTsPCXsgFnFJ2HmltRQr1JB+I4CPasfsBp3xqF23hywUuW6fOsHZvv +g5QU7qYfaoxG6E8krGpiibocF5EKXtpEYzDOBFoDS9uNVBAD/LzS7OGtTFr5x3qL +is3eccwNClQS1jeX8Guxam+TlO8XaqnQLCIpdau20/sge6PqXKXauKZiBTGCak1j +zVDQ/sro3VRPePusNHK1CdOi6wiruXw4ZLWO3aEHibi8LbgfwymxXHEtJO5zwFcD +qAnp7KEAkOG8y5LR0FfwWWYnqUZxWJ0ua2Acf8gL8o6DO5pVyJSYrdgCpWjwEWcp +Ms2iit9bCNIMaH6EVgLA2NWCuIL9xAFdXqw/VXrMVK3XXftzNvayvLJCH2eintRg +IKLO/ewISKIFQd3+II3/MM80eUvKGtfi8Y1mj1zyQtcPVykru5DEHjpaLs2SPxdI +Lp+HGQo/NvzwdpIV+8TQ +=eD8w +-----END PGP PUBLIC KEY BLOCK----- +``` + +받은 파일을 확인하는 법: 위 키를 `gpg --import`로 넣고 `gpg --verify <파일>.asc <파일>`. 배포 토큰 secret 이름은 설계 문서의 `PACKAGES_TOKEN`이 아니라 등록된 `PACKAGE_TOKEN`이다. + +## 이력 + +- 2026-08-14 ~ 2026-11-07: 백엔드 템플릿 `clean-architecture-backend-template` 안에서 만들었다(`src/messaging/` → 2026-11-07부터 `src/platforms/messaging/`). +- 2026-11-08: `git filter-repo`로 그 경로들과 `docs/messaging/`, 설계서, `messaging-certification.yml`, 저장소 계약 테스트 `MessagingPublicSurfaceContractTest`의 이력을 이 repo로 옮겼다(템플릿 main `2959eff0` 기준). 옮긴 모듈 폴더의 트리 해시는 템플릿 기준 커밋과 같다. +- filter-repo가 커밋 SHA를 모두 다시 썼다. 코드 주석과 문서가 부르는 커밋 SHA와 리뷰 ID(`MSG-…`, `RR-…`, `S7-#9c` 등)는 **템플릿 repo** 기준이다. 그 리뷰 문서는 템플릿 `docs/reviews/`에 남아 있다. +- 설계와 결정: design-docs `repo-structure/05-library-repos.md`(소유자 승인 2026-11-07, 이름 변경 2026-11-08). diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..0e48bc2 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,29 @@ +# 문서 지도 + +## 1. 어디에 무엇이 있나 + +| 폴더 | 종류 | 고치는 법 | +| --- | --- | --- | +| `work/` | 작업 방법(고치기, 게이트, 릴리스) | 살아 있는 문서. 동작이 바뀌면 같은 변경에서 고친다 | +| `messaging/` | 제품 문서(설정 참조, 전달 보장, outbox·inbox, 재시도·DLQ, 보안, 운영, 지원 표) | 살아 있는 문서. 몇몇은 시험이 읽는다(`MessagingDocumentationContractTest`, `MessagingConfigurationBindingTest`) | +| `design/` | 설계서 | 기록. 본문은 고치지 않는다 | +| `adr/` | 결정 기록(양식 `0000-template.md`) | 기록. 본문은 고치지 않는다 | +| `ledger/` | 예측·실측 장부 | 줄을 더하기만 한다 | +| `vision.md`, `problem-statement.md` | 방향, 풀 문제 | `vision.md`는 소유자만 쓴다 | + +## 2. 기록 문서의 머리 블록 + +`adr/`와 `design/`의 문서는 맨 위에 머리 블록을 둔다. 본문은 쓴 때의 원문이고, 지금도 맞는지는 머리 블록이 말한다. + +```markdown + +> **결정 기록** 본문은 결정한 때의 내용이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. + +- 상태: 채택 | 대체됨(무엇으로) | 폐기 +- 작성일: YYYY-MM-DD +- 요약: 한 문장 +- 현재 정본: 지금 동작을 설명하는 살아 있는 문서 경로 + +``` + +지난 결정이 바뀌면 본문은 두고 「상태」와 「현재 정본」만 고친다. 템플릿에서 옮겨 온 기록의 본문 경로(`src/messaging/…`, `src/platforms/…`)는 그 결정 때의 템플릿 경로다. diff --git a/docs/messaging/configuration-reference.md b/docs/messaging/configuration-reference.md index 07130a2..6695a6c 100644 --- a/docs/messaging/configuration-reference.md +++ b/docs/messaging/configuration-reference.md @@ -26,8 +26,8 @@ producing-service identity다. ## Outbox -application의 발행 경로는 하나다(2026-09-28): `outbox_event` 표와 `composition:outbox-relay`. vendored -platform의 `messaging_outbox`(`outbox-inbox.md`)는 이 경로에 쓰이지 않는다 — 두 모델의 상태 대응은 +백엔드 템플릿 application의 발행 경로는 하나다(2026-09-28): `outbox_event` 표와 `composition:outbox-relay`. +이 라이브러리의 `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` diff --git a/docs/messaging/cutover.md b/docs/messaging/cutover.md index 1a79eaa..02c542e 100644 --- a/docs/messaging/cutover.md +++ b/docs/messaging/cutover.md @@ -29,7 +29,7 @@ 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와 + (템플릿 `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. diff --git a/docs/messaging/experimental-policy.md b/docs/messaging/experimental-policy.md index de8f5b1..2c163ca 100644 --- a/docs/messaging/experimental-policy.md +++ b/docs/messaging/experimental-policy.md @@ -19,7 +19,7 @@ stopsAcceptingNewWorkDuringShutdown 현재 Experimental 어댑터는 없다. Kafka Share Group·Pulsar·NATS JetStream(Experimental), RabbitMQ, Spring Cloud Stream bridge(Optional)는 SDK 없는 seam이거나 선택할 수 없는 상태여서 2026-09-25에 -삭제했다(`docs/capability-status.md` 제거 표). 이 문서는 새 어댑터를 들일 때 지킬 규칙이다. +삭제했다(템플릿 `docs/capability-status.md` 제거 표). 이 문서는 새 어댑터를 들일 때 지킬 규칙이다. ## 규칙 diff --git a/docs/messaging/outbox-inbox.md b/docs/messaging/outbox-inbox.md index 1567cc9..6e1e3f0 100644 --- a/docs/messaging/outbox-inbox.md +++ b/docs/messaging/outbox-inbox.md @@ -1,9 +1,9 @@ # 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`, +> **이 문서의 Outbox는 이 라이브러리의 outbox다**(`messaging_outbox` 표, +> `messaging-reliability`의 `OutboxRelay`). 백엔드 템플릿 application이 쓰는 outbox는 그것이 아니다. +> 템플릿 application은 `outbox_event` 표(`adapter:outbound:persistence-jpa`)에 append하고, relay는 +> `composition:outbox-relay`가 돌린다. 그 동작과 운영은 템플릿 repo의 `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). @@ -20,9 +20,9 @@ > | publisher가 예외를 던졌고 시도 예산을 다 썼다 | `DEAD`(종단, 수동 처분) | `EXHAUSTED`(종단) | > | 운영자가 재시도를 멈췄다 | `PARKED`(수동 재개·skip) | 없음 | > -> **이 템플릿 application의 소비 경로**: application의 `MessageHandler`와 inbox 부품(애플리케이션 +> **백엔드 템플릿 application의 소비 경로**: application의 `MessageHandler`와 inbox 부품(애플리케이션 > DataSource 위 `JdbcInboxRepository`, `PlatformTransactionManager` 위 `TransactionRunner`)은 -> `adapter:inbound:messaging`(`src/adapter/inbound/messaging/README.md`)이 둔다. platform starter는 두 +> 템플릿의 `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의 선언으로 만든다. @@ -152,10 +152,10 @@ consume 계약은 `MessageHandler` 하나다. handler를 bean으로 등록하 - `Reject`는 at-most-once destination에서만 버리고, 그 밖에서는 dead letter로 보낸다. 실제 왕복·중복 제거·DLQ는 `MessagingKafkaConsumeQualificationTest`(Kafka + PostgreSQL Testcontainers)가 확인한다. -애플리케이션 경로(앱 outbox relay가 발행 → `adapter:inbound:messaging`이 조립한 inbox와 JPA 트랜잭션 → -handler)의 중복 전달·실패 재처리는 `InboxRedeliveryIntegrationTest`(lane +템플릿 애플리케이션 경로(앱 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` +(`@SystemCaller` handler가 `@SystemInvoked` use case를 직접 만든다)은 템플릿 `docs/manual/09-outbox-events.md` 「소비」 4단계다. ### 복합 키 @@ -176,7 +176,7 @@ repository port에는 개수 제한 없는 삭제 메서드가 없다. ## CDC 대안 relay는 polling 하나뿐이다. Debezium Event Router 매핑(`DebeziumOutboxEventRouter` 등)은 조립하는 -곳이 없어 2026-09-25에 삭제했다(`docs/capability-status.md` 제거 표). `messaging_outbox`의 +곳이 없어 2026-09-25에 삭제했다(템플릿 `docs/capability-status.md` 제거 표). `messaging_outbox`의 `routing_key` 컬럼은 남아 있으므로 CDC를 다시 들일 때 그 컬럼을 message key로 쓴다. ## Claim Check diff --git a/docs/messaging/support-matrix.md b/docs/messaging/support-matrix.md index d0325b2..b82ff73 100644 --- a/docs/messaging/support-matrix.md +++ b/docs/messaging/support-matrix.md @@ -9,9 +9,9 @@ > **삭제된 어댑터.** RabbitMQ(선택할 수 없던 validator·설정 모음), Pulsar·NATS JetStream·Kafka Share > Group(Experimental, SDK 없는 seam), Spring Cloud Stream bridge, Debezium outbox 매핑은 2026-09-25에 -> 삭제했다. 복구 경로는 `docs/capability-status.md`의 제거 표에 있다. +> 삭제했다. 복구 경로는 백엔드 템플릿 `docs/capability-status.md`의 제거 표에 있다. -> **인증 근거.** 이 표의 버전은 이 저장소의 컨테이너 레인이 실제로 실행한 이미지다. 이전 판은 +> **인증 근거.** 이 표의 버전은 이 저장소의 컨테이너 레인이 실제로 실행한 이미지다(`config/testing/container-images.properties`). 이전 판은 > Kafka 4.2/4.3을 선언했지만 fixture는 `apache/kafka:4.1.0`, lockfile client는 4.1.1이었다 — 표와 > 코드 상수가 서로 일치했을 뿐 어느 쪽도 실행된 적이 없었다. 장애 시나리오 커버리지도 마찬가지로 > `BrokerFailureMatrix.shipped()` 하드코딩이 아니라 레인이 낸 증거(`BrokerCertificationEvidence`)에서 @@ -24,10 +24,10 @@ > `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`가 소유한다. +> `config/architecture/modules.json`은 messaging leaf의 `gradle_path`와 허용 의존성을 관리하지만 +> `runtime_memberships` 필드는 없다. 실제 런타임 편입은 소비하는 앱의 Gradle 의존성(백엔드 템플릿은 +> `app-bootstrap`이 고르는 adapter)과 starter / auto-configuration 경로가 결정한다. 아래 등급은 "무엇이 증명되었는가"를 말하며 런타임 편입 여부와 +> 같은 축이 아니다. 자세한 composition/cutover 상태는 `messaging/AGENTS.md`가 소유한다. ## 브로커 등급 diff --git a/docs/problem-statement.md b/docs/problem-statement.md index 0b41511..00c8f8f 100644 --- a/docs/problem-statement.md +++ b/docs/problem-statement.md @@ -5,30 +5,39 @@ ## 고객의 말 그대로 -- (채울 것: 고객이 실제로 한 말을 따옴표로. 해석하지 않는다) +- 소유자(2026-11-07): 「템플릿 repo 안에 프로젝트 계층이 아닌 라이브러리 폴더가 있으면 안 된다. 커스텀 라이브러리는 별도 repo로 관리하고, 매뉴얼에 관리 대상으로 둔다.」 +- 고객은 이 라이브러리를 받아 쓰는 백엔드 서비스(백엔드 템플릿과 그 파생 서비스)와 그 서비스를 만드는 사람·에이전트다. ## 지금은 어떻게 버티나 -- (채울 것: 고객이 지금 쓰는 우회 방법과 그 비용) +- 2026-11-08까지 이 코드는 템플릿 주 빌드 안의 family(`src/platforms/messaging`)였다. 템플릿의 build-logic·카탈로그·registry를 그대로 썼고, 인증 lane은 템플릿의 별도 workflow(`messaging-certification.yml`)가 주 1회 돌렸다. +- 템플릿 adapter 넷이 `project(':messaging:…')`로 이 코드를 직접 받았다. 템플릿 JPA leaf의 migration 시험은 이 코드의 migration 폴더를 경로(`../../../platforms/messaging/…`)로 읽었다. +- 템플릿을 받은 파생 서비스는 쓰지 않아도 메시징 코드 450여 파일을 함께 받았다. 템플릿 재사용 체크리스트(「`dev.caskeleton`을 새 패키지로 바꾼다」)가 이 패키지까지 바꾸게 만들었다. ## 하지 않는 것 -- (채울 것: 이번에 일부러 풀지 않는 문제, 만들지 않는 기능) +- 새 브로커 adapter. RabbitMQ·Pulsar·NATS 등은 2026-09-25에 지웠다. 다시 들이려면 `docs/messaging/experimental-policy.md`를 따른다. +- Maven Central 배포. 템플릿 밖 공개 소비자가 생기면 본다. +- BOM. 소비자가 템플릿 하나라 카탈로그 버전 한 칸으로 충분하다. 템플릿 밖 소비자가 모듈 3개 이상을 쓰면 다시 본다. +- SNAPSHOT 배포. 같이 고칠 때는 composite build를 쓴다. ## 성공 기준 | 기준 | 구체적으로 | 어떻게 재나 | 목표 값 | 기한 | |---|---|---|---|---| -| (채울 것) | | | | | +| 혼자 빌드된다 | 템플릿 없이 PR·main 단계가 초록. main은 실제 Kafka로 인증 증거를 다시 만든다 | Gitea Actions `pr`·`main` 실행 결과 | 초록 | 2026-11-08 | +| 배포된다 | 태그 하나로 서명된 모든 모듈이 Gitea Packages에 올라가고 익명으로 읽힌다 | release.yml, `maven-metadata.xml` | `v1.0.0` 게시 | 2026-11-08 | +| 템플릿이 버전으로 받는다 | 템플릿에 메시징 폴더가 없고, 쓰는 leaf가 `dev.cakit.messaging:*:1.0.0`으로 같은 lane을 통과한다 | 템플릿 `git ls-files src/platforms`, 템플릿 `integrationCheck` | 0, 초록 | 2026-11-08 PR | ## 세 관점 점검 | 관점 | 묻는 것 | 답 | |---|---|---| -| 비즈니스 | 돈이 되나, 누가 대가를 치르나 | (채울 것) | -| 기술 | 만들 수 있나, 가장 위험한 가정은 | (채울 것) | -| 고객 | 쓸모 있나, 지금 방법보다 나은가 | (채울 것) | +| 비즈니스 | 돈이 되나, 누가 대가를 치르나 | 템플릿 유지비를 줄인다. 대가는 CI·build-logic 사본·release secret이 한 벌 더 생기는 것 | +| 기술 | 만들 수 있나, 가장 위험한 가정은 | 템플릿이 좌표로 바꿔도 lockfile의 외부 의존성 집합이 같다는 가정(설계 16절 H6). 배포한 POM·module 파일의 버전 선언이 해석을 바꾸면 깨진다 | +| 고객 | 쓸모 있나, 지금 방법보다 나은가 | 쓰는 서비스는 버전으로 받고, 쓰지 않는 서비스는 아무것도 받지 않는다 | ## 되돌릴 수 없는 결정 -- (채울 것: 되돌리기 비싼 결정만 여기 적고 `docs/adr/`에 결정 기록을 남긴다. 되돌릴 수 있는 결정은 빨리 한다) +- 배포한 버전은 지우지 않는다(`docs/work/release.md` 2절). 같은 버전은 다시 올릴 수 없다. +- Maven group·Java 패키지 `dev.cakit.messaging`, 설정 접두사 `app.messaging`, migration 위치 `db/migration/messaging`. 바꾸면 모든 소비자의 MAJOR다. 근거는 design-docs `repo-structure/05-library-repos.md` 6.3절. diff --git a/docs/work/README.md b/docs/work/README.md new file mode 100644 index 0000000..c7afbc7 --- /dev/null +++ b/docs/work/README.md @@ -0,0 +1,41 @@ +# 작업 방법 — messaging-library를 고칠 때 + +이 repo에서 일을 맡은 사람과 에이전트가 먼저 읽는다. 루트 `AGENTS.md`의 「꼭 지킬 것」이 이 문서보다 먼저다. + +## 1. 일의 종류와 읽을 곳 + +| 일 | 먼저 읽을 곳 | 끝났다는 증거 | +| --- | --- | --- | +| 모듈 코드 고치기·기능 더하기 | `messaging/AGENTS.md`(family 규칙, 공개 표면 정책), 관련 제품 문서(`docs/messaging/`) | 바꾼 모듈 `check` + `ci`(2절) | +| Kafka adapter·전달 보장 바꾸기 | `messaging/AGENTS.md` 「Stable 승격에 필요한 증거」, `docs/messaging/support-matrix.md` | 위 + `mainCheck`(인증 lane과 증거 게이트) | +| outbox·inbox·admin journal, migration | `docs/messaging/outbox-inbox.md` | 위 + `integrationCheck`. 적용된 migration은 고치지 않고 새 버전 파일을 더한다 | +| 공개 타입·설정 키(`app.messaging.*`) 바꾸기 | `release.md` 2절 | `CHANGELOG.md`에 옮기는 법, 템플릿 쪽 영향 확인(3절) | +| 빌드 규칙(build-logic) 고치기 | `build-logic/AGENTS.md`, `build-logic/UPSTREAM.md` | `buildLogicTest`(`ci` 안) | +| 릴리스 | `release.md` | release.yml 초록, 익명 메타데이터에 새 버전 | +| 리뷰 | 아래 2절의 게이트 목록과 루트 `AGENTS.md` 「꼭 지킬 것」 | 발견마다 위치·재현·고칠 곳 | + +## 2. 검증 + +- 진입점은 `scripts/verify.sh <단계>`다. 소유자 환경에서는 Gradle·Docker를 desktop에서만 돌린다: `--on desktop`을 붙이면 지금 작업 트리를 패치로 옮겨 잠금(`/tmp/claude-gates/heavy.lock`) 아래에서 돌린다. +- 무엇을 돌릴지는 `gates.md`다. 완료를 말하기 전에 바꾼 것에 맞는 게이트를 돌리고, 못 돌렸으면 이유를 적는다. + +## 3. 백엔드 템플릿과 같이 고치기 + +백엔드 템플릿은 이 라이브러리를 버전으로 받는다(카탈로그 칸 `messagingLibrary`, 쓰는 곳은 `adapter:outbound:messaging`, `adapter:outbound:messaging-kafka`, `adapter:inbound:messaging`, `adapter:outbound:persistence-jpa`의 migration 시험, `composition:outbox-relay`의 시험). 템플릿 쪽 절차는 템플릿 `docs/work/reference/related-repos.md`다. + +1. 이 repo와 템플릿에 브랜치를 하나씩 만든다. 두 repo를 같은 부모 폴더에 둔다. +2. 템플릿 `src/`에서 명령 줄로만 이 repo를 끼운다. 파일은 바꾸지 않는다. + + ```bash + ./gradlew --include-build ../../messaging-library <태스크> + ``` + +3. 그 상태로 lockfile을 쓰거나 커밋하지 않는다. 끼운 모듈은 lockfile 밖으로 빠질 수 있다. +4. 병합 순서는 하나다: 이 repo PR 병합 → 태그·릴리스 → 템플릿 PR에서 버전을 올리고 lockfile을 다시 쓴다 → 템플릿 병합. 끼운 상태로만 통과하는 템플릿 PR은 병합하지 않는다. +5. 공개 API·설정 키·migration을 바꾸는 PR은 본문에 템플릿 쪽 영향(끼운 상태로 돌린 태스크와 결과)을 적는다. + +## 4. 이 repo에서 정한 것 + +- 결정 기록은 `docs/adr/`에 쌓는다. 템플릿에서 옮겨 온 결정 기록은 없다(메시징 결정은 설계서와 템플릿 리뷰에 있다). 새 결정은 `docs/adr/0000-template.md` 양식으로 `ADR-MSG-001`부터 쓴다. +- 문서는 한국어로 쓴다. 지난 결정을 고칠 때는 본문이 아니라 머리 블록의 「상태」·「현재 정본」만 고친다(`docs/README.md` 2절). +- 커밋·PR 규칙은 design-docs `conventions/commit-and-pr.md`다. `main`에는 PR로 넣는다(첫 배포 전 첫 커밋들만 예외였다). diff --git a/docs/work/gates.md b/docs/work/gates.md new file mode 100644 index 0000000..62d7f6d --- /dev/null +++ b/docs/work/gates.md @@ -0,0 +1,33 @@ +# 게이트 — 무엇을 언제 돌리나 + +단계 태스크는 루트 `build.gradle`이 정한다. workflow는 단계마다 Gradle 한 줄이고, 어떤 모듈·lane·검사가 들어가는지는 workflow가 아니라 Gradle이 정한다. + +## 1. 단계 + +| 단계 | 언제 | 명령(`scripts/verify.sh`) | 들어 있는 것 | +| --- | --- | --- | --- | +| `ci` | PR(`pr.yml`) | `pr` | 모듈 `check` 전부(단위 시험, Spotless, Checkstyle, Error Prone, `messaging-testkit`의 저장소 계약 lane), SpotBugs(main·test), lockfile, `architectureCheck`, build-logic 시험. 그리고 `verifyStrictLaneStages --dry-run` | +| `mainCheck` | main push·매일 03:30 KST(`main.yml`) | `main` | `ci` + `integrationCheck`(Testcontainers Kafka·Toxiproxy·PostgreSQL) + 브로커 인증 증거 게이트 `verifyMessagingCertificationEvidence` | +| `releaseCheck` | `vX.Y.Z` 태그(`release.yml`) | `release` | 버전 확인, hermetic lane(`testLaneCheck`), `integrationCheck`, 인증 증거 게이트, SBOM, 의존성 취약점 검사 | +| `release` | `vX.Y.Z` 태그 | — | `releaseCheck` 뒤 Gitea Packages에 서명해 올리고 익명으로 다시 읽는다 | +| `releaseRehearsal` | 손으로 | `release` | `releaseCheck` 뒤 `build/staging-repository`에 올리고 파일마다 확인. 비밀 값 없이 돈다 | + +성능 lane은 없다. `messaging-kafka`·`messaging-testkit`의 JMH 벤치마크(`./gradlew :messaging:<모듈>:jmh`)는 게이트가 아니다. + +## 2. 바꾼 것에 맞는 게이트 + +| 바꾼 것 | 최소로 돌릴 것 | +| --- | --- | +| 모듈 하나의 코드 | `./gradlew :check`(path는 registry), 끝나기 전에 `scripts/verify.sh pr` | +| `messaging-kafka`, 전달 보장·실패 분류 | 위 + `./gradlew :messaging:messaging-kafka:verifyMessagingCertificationEvidence`(Docker). 시나리오가 바뀌면 만들어진 `build/messaging-certification/broker-certification-evidence.jsonl`을 `messaging-testkit/src/main/resources/messaging/`에 덮어 같은 변경에 넣는다 | +| `messaging-reliability*`, migration, starter 조립 | 위 + `./gradlew integrationCheck`(Docker) | +| 모듈의 `api`·`implementation` 범위, 공개 시그니처, `app.messaging` 설정 타입 | `./gradlew :messaging:messaging-testkit:repositoryContractTest` | +| `build.gradle`, `build-logic/`, registry, workflow | `scripts/verify.sh pr`(lane 단계 검사가 workflow를 읽는다) | +| 의존성 버전, lockfile | `./gradlew resolveAndLockAll --write-locks` 후 `scripts/verify.sh pr`, 릴리스 전이면 `scripts/verify.sh release` | +| 테스트 컨테이너 이미지(`config/testing/container-images.properties`) | `scripts/verify.sh main`. Kafka 이미지가 바뀌면 인증 manifest도 다시 만든다(위 `messaging-kafka` 줄) | + +## 3. 증거로 남길 때 + +- 게이트, rc, 실행 직전 부하(`uptime`), 로그 경로, 대상 트리(커밋 또는 `git write-tree`), 캐시를 썼는지를 적는다. +- 증거로 쓰는 실행은 `--rerun-tasks`로 캐시 결과를 쓰지 않는다. 테스트 수는 `build/test-results/**.xml`에서 센다. +- 인증 증거 줄의 `gitCommit`은 lane이 `GITHUB_SHA`(없으면 `local`)로 적는 출처다. 게이트는 `gitCommit`·`observedAt`을 빼고 시나리오 집합을 비교한다. diff --git a/docs/work/release.md b/docs/work/release.md new file mode 100644 index 0000000..5956866 --- /dev/null +++ b/docs/work/release.md @@ -0,0 +1,88 @@ +# 릴리스 — 태그에서 Gitea Packages까지 + +이 문서는 messaging-library 버전을 내는 절차다. 버전을 내는 사람(소유자)과 릴리스를 준비하는 에이전트가 읽는다. + +```text +main 병합 ──> 소유자가 태그 vX.Y.Z push ──> .gitea/workflows/release.yml (desktop-runner) + └─ ./gradlew releaseCheck release + 1. 태그 형식·버전 확인 (verifyReleaseVersion) + 2. hermetic lane + integration lane + 브로커 인증 증거 게이트 + (testLaneCheck, integrationCheck, verifyMessagingCertificationEvidence) + 3. SBOM 만들기 (releaseSbom, Trivy CycloneDX) + 4. 의존성 취약점 검사 (HIGH·CRITICAL, KEV) — 여기까지 실패하면 아무것도 안 올라간다 + 5. 모든 모듈 + SBOM 서명해서 올리기 (publish…ToGiteaRepository) + 6. 익명으로 maven-metadata.xml을 읽어 새 버전 확인 +``` + +## 1. 비밀 값 — 소유자가 둔다 + +에이전트는 토큰·키를 만들거나 secret에 넣지 않는다. 소유자가 2026-11-08에 repo secret 셋을 등록했다. + +| secret | 무엇 | 바꿀 때 | +| --- | --- | --- | +| `PACKAGE_TOKEN` | Gitea 개인 토큰. 권한은 `package` 읽기·쓰기만(repository·user 권한 없음). Gitea job 토큰(`GITEA_TOKEN`)은 패키지를 올릴 수 없어서 사람 토큰이 필요하다 | Gitea 웹 → 설정 → 애플리케이션에서 새로 만들어 secret을 덮어쓰고 옛 토큰을 지운다 | +| `SIGNING_KEY` | 서명용 PGP 비밀 키(ASCII armor 전체). 두 라이브러리(grpc, messaging)가 같은 키를 쓴다 | 새 키 쌍을 만들고 README 「서명」의 공개 키와 지문을 같은 PR에서 바꾼다. 만료(2028-11-07) 전에 한다 | +| `SIGNING_PASSWORD` | 그 키를 만들 때 정한 암호 한 줄. 키 파일이나 그 base64가 아니다 | 키와 함께 | + +- 이름: 설계(design-docs `repo-structure/05-library-repos.md` 7절)는 `PACKAGES_TOKEN`이라고 적었지만, 등록된 이름 `PACKAGE_TOKEN`에 workflow와 빌드를 맞췄다. 소유자에게 다시 등록을 부탁하지 않는다. +- 서명 키: RSA 4096, 지문 `92646CEAFE816CF8B9C249F0A1C936D7F791F8AB`, 2028-11-07 만료. 공개 키는 README 「서명」이다. +- 첫 태그는 `v1.0.0`이다(3절). + +**`SIGNING_KEY`에 넣는 것**은 키 지문이나 키 ID(16진수 40·16·8글자)가 아니라 비밀 키 파일 전체다. 파일 그대로(여러 줄)나 그 파일을 base64로 한 줄로 만든 값(`base64 -w0 signing-key.asc`) 둘 다 된다. 빌드가 base64를 풀어 쓴다(`SigningKeys`). + +```bash +gpg --armor --export-secret-keys 92646CEAFE816CF8B9C249F0A1C936D7F791F8AB > signing-key.asc +``` + +1. `signing-key.asc`를 열어 첫 줄 `-----BEGIN PGP PRIVATE KEY BLOCK-----`부터 끝 줄 `-----END PGP PRIVATE KEY BLOCK-----`까지 줄바꿈 그대로 복사한다. RSA 4096 키면 100줄 남짓이다. +2. Gitea → 그 repo(grpc-library, messaging-library 둘 다) → 설정 → Actions → Secrets → `SIGNING_KEY`를 고쳐 붙여 넣는다. +3. Actions → `signing-check` → Run workflow(main). 로그에 `PROBLEM` 줄이 없고 `gpg import: ok, secret key fingerprint 92646CEA…F791F8AB`, `signing with SIGNING_PASSWORD: ok`가 나오면 된다. 이 workflow는 값을 출력하지 않는다(`scripts/release/check-signing-key.sh`). +4. `signing-key.asc`를 지운다(`shred -u signing-key.asc`). + +## 2. 버전 규칙 + +- SemVer, repo 하나에 버전 하나. 모든 모듈이 같은 버전으로 나간다. 태그는 `vMAJOR.MINOR.PATCH`이고 접미사(`-rc.1` 등)는 없다. 다른 모양의 태그는 `ca.java-conventions`가 빌드 전에 거부한다. +- 공개 타입의 삭제·시그니처 변경, 설정 키(`app.messaging.*`) 바꾸기, 적용된 migration의 위치(`db/migration/messaging`)·내용 바꾸기는 MAJOR다. migration은 원래 고치지 않는다(새 버전 파일을 더한다). 커밋 제목에 `!`, 본문에 `BREAKING CHANGE:`, `CHANGELOG.md` 그 버전 절에 옮기는 법을 쓴다. +- 기능 추가는 MINOR, 고치기는 PATCH다. +- SNAPSHOT은 내지 않는다. Gitea는 같은 버전을 다시 받지 않는다. 개발 중 연결은 composite build로 한다(`docs/work/README.md` 3절). +- **배포한 버전은 지우지 않는다.** 잘못 나갔거나 일부만 올라갔으면 그 버전은 버리고 다음 PATCH를 낸다. Gitea는 owner의 삭제를 막지 않으므로 이것은 규칙으로 지킨다. + +## 3. 버전 내기 + +1. main이 초록인지 본다(main.yml 마지막 실행). +2. `CHANGELOG.md`에 그 버전 절을 쓰고 PR로 병합한다. +3. 올리기 전까지를 desktop에서 미리 돌려 본다(비밀 값 없이, 4절). 비밀 값을 넣거나 바꾼 뒤 첫 태그라면 `signing-check` workflow도 한 번 돌린다(1절). +4. 태그를 단다. + + ```bash + git tag -a v1.0.0 -m "messaging-library 1.0.0" + ``` + + ```bash + git push origin v1.0.0 + ``` + +5. release.yml 실행이 초록인지 Gitea Actions 화면에서 본다. 마지막 줄들에 모듈마다 `published: dev.cakit.messaging:<모듈>:<버전>`이 찍힌다. +6. 템플릿 PR로 카탈로그 버전(`messagingLibrary`)을 올린다. 절차는 템플릿 `docs/work/reference/related-repos.md`다. + +## 4. 올리기 직전까지 미리 돌리기 + +```bash +scripts/verify.sh release --on desktop +``` + +`releaseRehearsal`이 `releaseCheck`를 돌고, 모든 모듈과 SBOM을 `build/staging-repository`에 올린 뒤 파일마다 확인한다(jar·sources·javadoc·POM·module 파일, 체크섬 넷, POM·module의 모든 의존성에 버전이 있는지). `SIGNING_KEY`가 환경에 있으면 `.asc`도 확인한다. 버전은 `RELEASE_VERSION`이 없으면 `0.0.0`이다. + +## 5. 실패했을 때 + +| 어디서 | 뜻 | 할 일 | +| --- | --- | --- | +| 1~4단계, 서명 | 아무것도 올라가지 않았다 | 고쳐서 main에 병합한다. 그 버전의 파일이 Packages에 하나도 없으면(`maven-metadata.xml`에 없음) 태그를 지우고 고친 main 커밋에 같은 태그를 다시 단다. 하나라도 올라갔으면 다음 PATCH를 쓴다 | +| 서명 직전 `verifySigningKey`, 또는 `Could not read PGP secret key` | 서명 비밀 값이 키로 읽히지 않는다 | `signing-check` workflow의 `PROBLEM` 줄이 원인이다(지문을 넣음, 줄바꿈 잃음, BEGIN·END 줄 빠짐, base64 손상, 다른 키, 암호 칸에 키를 넣음, 틀린 암호). 1절대로 다시 넣는다 | +| 5단계 중간 | 일부 모듈만 올라갔을 수 있다 | 그 버전은 버린다(지우지 않는다). 원인을 고치고 다음 PATCH를 낸다. `CHANGELOG.md`에 버린 버전을 적는다 | +| 6단계 | 올라갔지만 익명으로 안 읽힌다 | owner 공개 설정을 확인한다. 템플릿 이미지 빌드가 토큰 없이 읽는다는 전제(설계 8.3절 R1)가 깨진 것이다 | + +## 6. 취약점 정책 + +- Trivy(버전·SHA-256은 `scripts/tool.sh`)가 커밋된 lockfile을 본다. HIGH·CRITICAL은 막고, MEDIUM·LOW는 보고만 하고, CISA KEV 목록에 있으면 등급과 상관없이 막는다. KEV 목록을 못 받으면 막는다. +- 예외는 `.trivyignore.yaml` 한 곳에만 둔다. 항목마다 이유(`statement`)와 90일 안의 만료(`expired_at`)를 적고 PR로 넣는다. diff --git a/messaging/AGENTS.md b/messaging/AGENTS.md index 9c68440..a01a183 100644 --- a/messaging/AGENTS.md +++ b/messaging/AGENTS.md @@ -1,7 +1,7 @@ # messaging — 메시징 플랫폼 family의 지역 정본 이 문서는 messaging family의 **지역 정본(local authority)**이다. leaf 목록·gradle path·허용 의존성은 -`src/config/architecture/modules.json`이 SSOT이며 이 문서는 그것을 복제하지 않는다. 여기서 정하는 +`config/architecture/modules.json`이 SSOT이며 이 문서는 그것을 복제하지 않는다. 여기서 정하는 것은 registry가 표현할 수 없는 것들이다: family별 framework 규칙, public surface 정책, Stable 승격에 필요한 증거, runtime membership이 비어 있다는 사실의 의미. @@ -33,11 +33,11 @@ JDBC이고 SQL은 `jsonb` · `FOR UPDATE SKIP LOCKED` · `ON CONFLICT` · `TIMES ### 공용 다이제스트 헬퍼를 복사해 두는 이유 `messaging-admin`(`HmacApprovalVerifier`, `PlanDigest`)과 `messaging-claim-check` -(`ClaimCheckIntegrityGuard`)는 SHA-256·HMAC-SHA256 계산을 자기 안에 둔다. 템플릿의 -`shared-contract` `digest/Sha256`·`HmacSha256`을 쓰지 않는 것은 의도다. 이 family는 이 애플리케이션의 -계층이 아니라 자기 API·SPI·composition을 가진 다른 제품이고(2026-08-14 messaging 모듈 리뷰 뒤 소유자가 정한 배치), `messaging:*` leaf는 -`domain-core`·`application-core`·`shared-contract` 어느 타입에도 의존하지 않는다. 헬퍼 하나 때문에 -registry edge를 주면 그 경계가 깨진다. 복사본을 고칠 때(키 길이 검사, constant-time 비교 등)는 +(`ClaimCheckIntegrityGuard`)는 SHA-256·HMAC-SHA256 계산을 자기 안에 둔다. 백엔드 템플릿의 +`shared-contract` `digest/Sha256`·`HmacSha256`을 쓰지 않는 것은 의도다. 이 family는 템플릿 애플리케이션의 +계층이 아니라 자기 API·SPI·composition을 가진 다른 제품이고(2026-08-14 messaging 모듈 리뷰 뒤 소유자가 정한 배치, 2026-11-08에 별도 repo로 옮김), `messaging:*` leaf는 +템플릿의 `domain-core`·`application-core`·`shared-contract` 어느 타입에도 의존하지 않는다. 다른 repo가 된 +지금은 그 타입에 닿을 길 자체가 없다. 복사본을 고칠 때(키 길이 검사, constant-time 비교 등)는 `shared-contract`의 정본과 같은 규칙인지 함께 본다. ### 인증·인가 거부의 발행 재시도 여부 (Publish retryability of authentication and authorization) @@ -84,21 +84,24 @@ relay, `composition:outbox-relay`)을 부르지 않는다 — "flag를 믿는 pu ## Application runtime에 포함되는 기준 -기본 조립에는 Messaging family가 없다. 서비스가 `app-bootstrap/build.gradle`에 +소비자는 지금 백엔드 템플릿 하나다(`dev.cakit.messaging:*`를 Gitea Packages에서 버전으로 받는다). +템플릿의 기본 조립에는 Messaging family가 없다. 서비스가 템플릿 `app-bootstrap/build.gradle`에 `runtimeOnly project(':adapter:outbound:messaging-kafka')` 한 줄을 넣으면 그 모듈이 bridge와 -`messaging-spring-boot-starter`(Kafka transport 포함)의 transitive project graph를 runtime에 싣는다. 이 -사실의 SSOT는 Gradle `runtimeClasspath`이며 registry에 동일한 membership 목록을 복제하지 않는다. +`messaging-spring-boot-starter-kafka`(core starter 포함)의 transitive graph를 runtime에 싣는다. 이 +사실의 SSOT는 그 앱의 Gradle `runtimeClasspath`이며 registry에 동일한 membership 목록을 복제하지 않는다. 모듈이 있으면 켜지고(`app.messaging.enabled` 기본 `true`), `APP_MESSAGING_ENABLED=false`로만 끈다. 일부 codec(cloudevents 등)·claim-check·testkit처럼 starter graph에 들어오지 않는 leaf는 build-only다. RabbitMQ·Pulsar·NATS·Kafka Share·Spring Cloud Stream bridge leaf와 Debezium outbox 매핑은 -2026-09-25에 삭제했다(`docs/capability-status.md` 제거 표). +2026-09-25에 삭제했다(템플릿 `docs/capability-status.md` 제거 표). 새 leaf를 application에 채택할 때는 starter 또는 composition dependency와 architecture edge policy, -qualification/support 상태를 함께 변경한다. +qualification/support 상태를 함께 변경한다. 소비하는 앱 쪽 edge(템플릿 registry의 「허용 라이브러리」 칸)는 +그 앱 repo에서 바꾼다. ## application이 이 family에 도달하는 경로 (cutover 완료) -리뷰(`docs/reviews/2026-08-14-messaging-module-code-review.md` §6.1·§6.3)가 정한 +아래 경로와 타입 이름은 백엔드 템플릿 쪽이다(이 repo에는 없다). 리뷰(템플릿 +`docs/reviews/2026-08-14-messaging-module-code-review.md` §6.1·§6.3)가 정한 `application-owned port → platform anti-corruption bridge → platform` 경로는 이제 존재한다. - application-owned port: `IntegrationEventPublishPort` @@ -121,7 +124,7 @@ canonical bridge의 producer identity는 `app.messaging.producer-id`로 명시 만들지 않으며 `spring.application.name`/host/pod 이름에서 identity를 발명하지 않는다. bridge가 없으면 relay가 발행할 곳이 없으므로 messaging 모듈이 켜진 상태에서는 기동이 거부된다. -`IntegrationEventEncoderPort`는 템플릿이 제공한다: `adapter:outbound:support`의 +`IntegrationEventEncoderPort`는 템플릿이 제공한다(이 라이브러리 타입이 아니다): `adapter:outbound:support`의 `JsonIntegrationEventEncoder`가 envelope v1(`shared-contract`의 `contracts/messaging/envelope/v1.schema.json`) 안에 payload record를 결정적 JSON으로 싣는다. 계약 catalog는 애플리케이션이 bean으로 등록한 `IntegrationEventContractContribution`뿐이고, 선언한 payload schema hash가 classpath의 schema 파일과 @@ -160,10 +163,9 @@ skip하는 인증 레인은 아무도 켜지 않은 브로커에 대해 성공 ## Focused test -leaf의 `gradle_path`를 registry에서 읽어 파생한다. +leaf의 `gradle_path`를 registry에서 읽어 파생한다. repo 루트에서 돌린다. ```bash -cd src ./gradlew :test --console=plain ``` diff --git a/messaging/messaging-spring-boot-starter/README.md b/messaging/messaging-spring-boot-starter/README.md index 2cb6c3e..1bbc69c 100644 --- a/messaging/messaging-spring-boot-starter/README.md +++ b/messaging/messaging-spring-boot-starter/README.md @@ -11,15 +11,15 @@ messaging-spring-boot-starter └─ messaging-spring-boot-starter-kafka # Kafka client/transport capability ``` -- 기본 app-bootstrap은 messaging을 싣지 않는다. 서비스는 `runtimeOnly +- 백엔드 템플릿의 기본 app-bootstrap은 messaging을 싣지 않는다. 서비스는 `runtimeOnly project(':adapter:outbound:messaging-kafka')` 한 줄로 Kafka capability를 고르고, 그 모듈이 - `:messaging:messaging-spring-boot-starter-kafka`(와 이 core starter)를 runtime으로 끌어온다. + `dev.cakit.messaging:messaging-spring-boot-starter-kafka`(와 이 core starter)를 runtime으로 끌어온다. - starter는 있으면 켜진다(`app.messaging.enabled` 기본 on). `app.messaging.enabled=false`로만 끈다. - 등록된 broker 계열은 Kafka 하나다. RabbitMQ 설정 키(`type: rabbitmq`, `addresses`, `prefetch` 등)는 transport 없이 바인딩만 되던 키라 삭제했고, 지금은 키 이름을 담아 기동이 거부된다. - reliability/admin의 추가 artifact 분리는 별도 구조 개선 여지로 남지만, broker SDK 동시 탑재 문제와 transport 선택 문제는 core/broker capability 분리로 해소했다. -- legacy R0 outbound bridge도 같은 원칙을 따른다. broker-neutral +- 템플릿의 outbound bridge도 같은 원칙을 따른다. broker-neutral `:adapter:outbound:messaging`과 Kafka 전용 `:adapter:outbound:messaging-kafka`가 분리돼 있다. ## 현재 broker/runtime 지원 범위 @@ -38,6 +38,6 @@ starter가 consumer runtime까지 자동 제공한다는 뜻이 아니다. ### RabbitMQ (삭제됨) production transport가 없어 선택할 수 없던 `messaging-rabbit`·`messaging-spring-boot-starter-rabbit`는 -2026-09-25에 삭제했다(`docs/capability-status.md` 제거 표). 현재 등록된 broker는 Kafka 하나다. +2026-09-25에 삭제했다(템플릿 `docs/capability-status.md` 제거 표). 현재 등록된 broker는 Kafka 하나다. `app.messaging.brokers..type: rabbitmq` 설정 family는 아직 바인딩·검증되지만 소비하는 transport가 없다.