옮겨 온 문서는 템플릿 안의 family를 전제로 쓰였다. 루트 지침은
하네스 뼈대의 빈 양식이고, 모듈 지침·제품 문서는 템플릿 경로
(src/platforms/messaging, src/config/…, cd src)와 템플릿 소비자
(app-bootstrap, adapter:*, composition:*)를 이 repo 안의 것처럼 부른다.
- AGENTS.md(38줄)·CLAUDE.md: 꼭 지킬 것 일곱(api 모듈 순수성, 템플릿
타입·경로 금지, 배포 버전·적용된 migration 불변, 인증 manifest 손으로
고치지 않기 등), 지도, 맡은 일, 검증 진입점.
- README.md: 받는 법(exclusiveContent dev.cakit), migration 위치, 지원 표
(Boot 4.0.9, kafka-clients 4.1.2, apache/kafka:4.1.0, PostgreSQL 16,
Java 21), 구조, 문서 지도, 서명 공개 키(지문 …A1C936D7F791F8AB,
grpc-library와 같은 키), 이력(템플릿 2959eff0에서 filter-repo).
- CHANGELOG.md: 1.0.0 절과 템플릿 안 코드에서 옮기는 법(패키지,
Kafka 설정 키, Gradle 좌표, 바뀌지 않는 것).
- docs/README.md, docs/work/{README,gates,release}.md,
docs/problem-statement.md: grpc-library와 같은 모양으로, 메시징의
인증 증거 게이트·migration 규칙·템플릿과 같이 고치는 경로를 넣었다.
docs/vision.md는 소유자가 쓸 자리라 비워 둔다.
- messaging/AGENTS.md, docs/messaging/*, starter README: registry 경로를
이 repo 기준으로, 템플릿 쪽 경로·타입은 「백엔드 템플릿의」로 밝혔다.
시험이 읽는 문장(지원 표의 broker·버전, 설정 참조의 YAML)은 바꾸지
않았다.
검증: scripts/verify.sh docs rc=0(vision.md 자리 알림만). desktop
mainCheck는 이 커밋 직전 트리에서 rc=0이었다. 문서가 시험에 읽히는
부분은 다음 desktop 실행으로 다시 본다.
Refs: design-docs repo-structure/05-library-repos.md 14.2절
This commit is contained in:
@@ -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
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택 | 대체됨(무엇으로) | 폐기
|
||||
- 작성일: YYYY-MM-DD
|
||||
- 요약: 한 문장
|
||||
- 현재 정본: 지금 동작을 설명하는 살아 있는 문서 경로
|
||||
<!-- 머리 블록 끝 -->
|
||||
```
|
||||
|
||||
지난 결정이 바뀌면 본문은 두고 「상태」와 「현재 정본」만 고친다. 템플릿에서 옮겨 온 기록의 본문 경로(`src/messaging/…`, `src/platforms/…`)는 그 결정 때의 템플릿 경로다.
|
||||
@@ -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`
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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` 제거 표). 이 문서는 새 어댑터를 들일 때 지킬 규칙이다.
|
||||
|
||||
## 규칙
|
||||
|
||||
|
||||
@@ -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<T>` 하나다. 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
|
||||
|
||||
@@ -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`가 소유한다.
|
||||
|
||||
## 브로커 등급
|
||||
|
||||
|
||||
@@ -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절.
|
||||
|
||||
@@ -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로 넣는다(첫 배포 전 첫 커밋들만 예외였다).
|
||||
@@ -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 <gradle path>: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`을 빼고 시나리오 집합을 비교한다.
|
||||
@@ -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로 넣는다.
|
||||
Reference in New Issue
Block a user