diff --git a/README.md b/README.md index c961aca4..e92ab1c1 100644 --- a/README.md +++ b/README.md @@ -84,7 +84,7 @@ DB, Redis, Kafka, 알림, 파일 서버 같은 부가 기능(capability)은 `src | 하려는 일 | 시작할 곳 | | --- | --- | -| 이 저장소에서 일하기(새 기능, 개선, 조사, 문서, 운영, 일 나누기) | 작업 매뉴얼 [docs/work/README.md](docs/work/README.md). 지도는 [CLAUDE.md](CLAUDE.md) | +| 이 저장소에서 일하기(새 기능, 개선, 조사, 문서, 운영, 일 나누기) | 작업 매뉴얼 [docs/work/README.md](docs/work/README.md). 지도는 [AGENTS.md](AGENTS.md) | | 새 업무 기능 만들기 | 개발 매뉴얼 [docs/manual/README.md](docs/manual/README.md)와 생성 명령 `scripts/new-feature.sh` | | 계약 확인하기(HTTP, 오류 코드, env 키, 메트릭, 헤더) | [docs/web/http-contract.md](docs/web/http-contract.md), `docs/registries/` | | 기능 운영하기(설정, 장애 대응) | 영역 운영 문서(`docs/jpa/`, `docs/redis/` 등), 장애 코드별 런북 `docs/runbooks/` | @@ -92,7 +92,7 @@ DB, Redis, Kafka, 알림, 파일 서버 같은 부가 기능(capability)은 `src | 예전 설계·계획·리뷰 찾기 | 기록 `docs/design/`, `docs/history/`, `docs/reviews/`. 쓴 때의 글이고 지금 동작은 각 머리 블록의 「현재 정본」을 읽는다 | | 템플릿 변경을 파생 서비스에 받기 | `docs/upgrade/` | -각 모듈의 규칙과 설계 근거는 그 모듈 폴더의 `CLAUDE.md`와 README에 있다(예: [domain-core](src/domain-core/README.md), [app-bootstrap](src/app-bootstrap/README.md)). +각 모듈의 규칙과 설계 근거는 그 모듈 폴더의 `AGENTS.md`와 README에 있다(예: [domain-core](src/domain-core/README.md), [app-bootstrap](src/app-bootstrap/README.md)). ## 검증 @@ -130,6 +130,6 @@ cd src ## 규칙과 기여 - 규칙의 정본은 [AGENTS.md](AGENTS.md)다. 「Prime Directive」의 HARD-STOP 조건을 어기면 동작하더라도 병합하지 않는다. -- 일을 시작할 때 읽는 지도는 [CLAUDE.md](CLAUDE.md)다. 일의 종류별 절차는 [docs/work/README.md](docs/work/README.md)다. -- 각 모듈의 지역 규칙은 가장 가까운 `src/**/CLAUDE.md`다. +- 일을 시작할 때 읽는 지도는 [AGENTS.md](AGENTS.md)다. 일의 종류별 절차는 [docs/work/README.md](docs/work/README.md)다. +- 각 모듈의 지역 규칙은 가장 가까운 `src/**/AGENTS.md`다. - 커밋 정책과 메시지 형식은 [docs/work/README.md](docs/work/README.md) 「커밋」이다. PR은 [.github/pull_request_template.md](.github/pull_request_template.md) 양식을 채운다. diff --git a/docs/README.md b/docs/README.md index effd1865..d6937d9a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -200,4 +200,4 @@ capability(부가 기능) 하나의 지원 범위, 설정, 보안, 운영, 마 - 실행되는 검증 스크립트는 문서가 아니다. `scripts/` 와 `.github/scripts/` 에 있다. - 모듈 레지스트리·Gradle 정책은 `src/config/architecture/modules.json` 과 `src/build.gradle` 이 소유한다. -- 각 모듈의 지역 규칙은 해당 모듈의 `src/**/CLAUDE.md` 가 소유한다. +- 각 모듈의 지역 규칙은 해당 모듈의 `src/**/AGENTS.md` 가 소유한다. diff --git a/docs/jpa/support-matrix.md b/docs/jpa/support-matrix.md index 50a1965d..b0b5cf92 100644 --- a/docs/jpa/support-matrix.md +++ b/docs/jpa/support-matrix.md @@ -48,7 +48,7 @@ major의 증거가 모두 같은 커밋 SHA를 지니기를 요구한다. 그래 H2는 두 번째 운영 대상이 아니다. 같은 위반에 다른 SQLSTATE를 보고하고, JSONB 연산자도, range 타입도, 동시 인덱스 빌드도 없다. H2에서 통과한 실행은 코드가 컴파일되고 돈다는 증거일 뿐이다. -`SKIP LOCKED`는 따로 한 문장이 필요하다. 두 문서가 다른 말을 했기 때문이다. 모듈의 `CLAUDE.md`는 측정을 기록한다. +`SKIP LOCKED`는 따로 한 문장이 필요하다. 두 문서가 다른 말을 했기 때문이다. 모듈의 `AGENTS.md`는 측정을 기록한다. H2 2.4.240은 `FOR UPDATE SKIP LOCKED`를 받고 잠긴 행을 정말로 건너뛴다. 그래서 outbox claim SQL이 두 vendor에서 같다. 이 문서는 전에 H2에 그런 보장이 없다고 했다. 둘은 서로 다른 질문에 각각 맞았고, 그 구별이 요점이다. **측정한 버전에서 관찰한 동작은 운영 보장이 아니고, PostgreSQL 계약 증거는 더욱 아니다.** 측정 덕분에 claim SQL에 vendor 분기가 필요 없고, 보장이 diff --git a/docs/manual/01-generator.md b/docs/manual/01-generator.md index 51adb4c1..d69e2cca 100644 --- a/docs/manual/01-generator.md +++ b/docs/manual/01-generator.md @@ -30,7 +30,7 @@ scripts/new-feature.sh Invoice --no-format # Gradle 없이 파일만 (뒤에 | 입력 | 규칙 | 어디서 막나 | | --- | --- | --- | | 이름 | PascalCase, 영숫자 | 스크립트 | -| 패키지 이름 | 이름을 소문자로(`purchaseorder`). Java 예약어이거나, 다섯 루트 중 어디든(어느 leaf든) 이미 있는 패키지 이름이면 거절 — 템플릿 패키지(`operation`, `lock`, `cache`…)가 모두 여기 걸린다. 목록은 `src/application-core/CLAUDE.md` 「Package ownership」 | 스크립트, `NamingConventionTest.FEATURE_PACKAGES_DO_NOT_REUSE_TEMPLATE_PACKAGE_NAMES` | +| 패키지 이름 | 이름을 소문자로(`purchaseorder`). Java 예약어이거나, 다섯 루트 중 어디든(어느 leaf든) 이미 있는 패키지 이름이면 거절 — 템플릿 패키지(`operation`, `lock`, `cache`…)가 모두 여기 걸린다. 목록은 `src/application-core/AGENTS.md` 「Package ownership」 | 스크립트, `NamingConventionTest.FEATURE_PACKAGES_DO_NOT_REUSE_TEMPLATE_PACKAGE_NAMES` | | HTTP 경로 | lowerCamel 복수형. AIP-122 모양 | 스크립트, `ForbiddenApiArchitectureTest.CONTROLLER_REQUEST_MAPPINGS_FOLLOW_AIP122` | | 이미 있는 파일·패키지 | 덮어쓰지 않고 멈춘다 | 스크립트 | diff --git a/docs/manual/02-new-feature.md b/docs/manual/02-new-feature.md index 0f36708c..aa781dc0 100644 --- a/docs/manual/02-new-feature.md +++ b/docs/manual/02-new-feature.md @@ -50,7 +50,7 @@ - **기본값**: aggregate를 통째로 저장·로드하면 domain 소유 `XRepository`. - **예외**: 읽기 모양이 aggregate와 다르면 application 소유 `XQueryPort` + projection(record). `QUERY_PORTS_DO_NOT_LEAK_DOMAIN_JPA_OR_WEB_TYPES`가 반환 타입을 검사한다. lease·claim 같은 기술 - 저장은 application 소유 `*StorePort`. 이름 규칙의 정본은 `src/application-core/CLAUDE.md`. + 저장은 application 소유 `*StorePort`. 이름 규칙의 정본은 `src/application-core/AGENTS.md`. ## 2단계 — application-core: 유스케이스와 포트 @@ -70,7 +70,7 @@ record, 오류 코드 enum과 carrier 예외. 예: `src/application-core/src/mai - **고르는 기준**: 결과를 커밋 뒤에 내보내야 하는가, 호출자와 독립적으로 커밋해야 하는가. - **기본값**: 쓰기 `tx.inWrite`, 읽기 `tx.inRead`. - **예외**: 커밋 확인 뒤 결과를 노출해야 하면 `inRootWrite`(바깥 트랜잭션이 있으면 거부). 감사·보상만 - `inNew`(루프 안 금지). 외부 HTTP·메시지 발행은 트랜잭션 밖. 표: `src/application-core/CLAUDE.md` + `inNew`(루프 안 금지). 외부 HTTP·메시지 발행은 트랜잭션 밖. 표: `src/application-core/AGENTS.md` 「Allowed transactional shapes」. ### 판단: 무엇을 반환하나 diff --git a/docs/manual/03-placement.md b/docs/manual/03-placement.md index 395780c9..f74d59d0 100644 --- a/docs/manual/03-placement.md +++ b/docs/manual/03-placement.md @@ -55,7 +55,7 @@ - ``는 템플릿 패키지 이름(`operation`, `outbox`, `lock`, `cache`, `secret`, `notification`…)과 겹치지 않는다. 겹치면 upstream 템플릿을 받을 때 같은 패키지 트리에서 병합 충돌이 난다. 업무 코드를 이름이 맞아 보이는 템플릿 패키지에 넣지도 않는다. -- **어느 패키지가 템플릿 소유인지와 이 규칙의 정본은 `src/application-core/CLAUDE.md` +- **어느 패키지가 템플릿 소유인지와 이 규칙의 정본은 `src/application-core/AGENTS.md` 「Package ownership」이다.** 매뉴얼은 목록을 다시 적지 않는다. 생성 명령이 이름을 거절하고, 생성 뒤에는 ArchUnit(`NamingConventionTest`의 package ownership 규칙 두 개)이 다시 막는다. - 이름 규칙은 같은 파일 「Naming convention」이 정본이다. diff --git a/docs/manual/05-idempotency.md b/docs/manual/05-idempotency.md index 25280c6c..707251aa 100644 --- a/docs/manual/05-idempotency.md +++ b/docs/manual/05-idempotency.md @@ -16,7 +16,7 @@ DB 커밋 중 연결 끊김 ─────────────────────────────────────▶ 500 DB_COMPLETION_UNKNOWN (retryable=false) ``` -정본: `docs/web/http-contract.md` 2절(wire 응답), `src/application-core/CLAUDE.md` 「Idempotency (KEYED)」 +정본: `docs/web/http-contract.md` 2절(wire 응답), `src/application-core/AGENTS.md` 「Idempotency (KEYED)」 (executor 구조), `docs/adr/ADR-JPA-003-completion-unknown.md`(커밋 결과 불명). ## 판단: 이 쓰기를 KEYED로 만드나 diff --git a/docs/manual/09-outbox-events.md b/docs/manual/09-outbox-events.md index 68affbe9..48a560ce 100644 --- a/docs/manual/09-outbox-events.md +++ b/docs/manual/09-outbox-events.md @@ -17,7 +17,7 @@ use case ── tx.inWrite ─┬─▶ repository.save(aggregate) ┐ DB 저장과 broker 발행을 따로 하면(dual write) 둘 중 하나만 성공하는 순간이 생긴다. outbox는 그 순간을 없앤다. 대가는 **적어도 한 번** 전달이다 — 소비자는 event id로 중복을 걸러야 한다. -정본: `src/application-core/CLAUDE.md`(이벤트 타입 표), `docs/messaging/outbox-inbox.md`, +정본: `src/application-core/AGENTS.md`(이벤트 타입 표), `docs/messaging/outbox-inbox.md`, `docs/messaging/delivery-guarantees.md`. ## 순서 diff --git a/docs/manual/11-checklist.md b/docs/manual/11-checklist.md index 70c210d2..2282613d 100644 --- a/docs/manual/11-checklist.md +++ b/docs/manual/11-checklist.md @@ -5,8 +5,8 @@ ## 배치·이름 - [ ] 배치를 03장 기준표로 정했다(기본: 계층 leaf 안 `` 패키지). -- [ ] 패키지 이름이 템플릿 패키지(`src/application-core/CLAUDE.md` 「Package ownership」)와 겹치지 않고, 업무 코드를 템플릿 패키지에 넣지 않았다. -- [ ] 이름이 `src/application-core/CLAUDE.md` 「Naming convention」을 따른다. +- [ ] 패키지 이름이 템플릿 패키지(`src/application-core/AGENTS.md` 「Package ownership」)와 겹치지 않고, 업무 코드를 템플릿 패키지에 넣지 않았다. +- [ ] 이름이 `src/application-core/AGENTS.md` 「Naming convention」을 따른다. ## domain diff --git a/docs/manual/README.md b/docs/manual/README.md index 47d7cc38..f3225d92 100644 --- a/docs/manual/README.md +++ b/docs/manual/README.md @@ -42,8 +42,8 @@ | --- | --- | | 계층 경계·금지 규칙·테스트 작성 규칙 | `AGENTS.md`(작업 지도는 `CLAUDE.md`) | | leaf 목록·허용 의존 | `src/config/architecture/modules.json` | -| 이름 규칙(유스케이스·포트·command·query) | `src/application-core/CLAUDE.md` 「Naming convention」. 기계 검사는 `src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/NamingConventionTest.java`와 `ApplicationBoundaryArchitectureTest.java` | -| 유스케이스 모양·트랜잭션 모양 | `src/application-core/CLAUDE.md` 「Canonical use case shape」「Allowed transactional shapes」 | +| 이름 규칙(유스케이스·포트·command·query) | `src/application-core/AGENTS.md` 「Naming convention」. 기계 검사는 `src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/NamingConventionTest.java`와 `ApplicationBoundaryArchitectureTest.java` | +| 유스케이스 모양·트랜잭션 모양 | `src/application-core/AGENTS.md` 「Canonical use case shape」「Allowed transactional shapes」 | | HTTP wire 계약(Envelope·멱등성 응답) | `docs/web/http-contract.md` | | 운영 오류 코드 | `docs/registries/error-codes.yaml`, `src/shared-contract/src/main/java/dev/caskeleton/shared/error/OperationalError.java` | | 엔티티 매핑·마이그레이션 | `docs/jpa/entity-mapping-guide.md`, `docs/jpa/migration-guide.md`, `docs/jpa/transaction-guide.md` | diff --git a/docs/messaging/support-matrix.md b/docs/messaging/support-matrix.md index 1a2e72c9..d0325b2e 100644 --- a/docs/messaging/support-matrix.md +++ b/docs/messaging/support-matrix.md @@ -27,7 +27,7 @@ > `modules.json`은 messaging leaf의 `gradle_path`와 허용 의존성을 관리하지만 > `runtime_memberships` 필드는 없다. 실제 런타임 편입은 `app-bootstrap`의 Gradle 의존성과 starter / > auto-configuration 경로가 결정한다. 아래 등급은 "무엇이 증명되었는가"를 말하며 런타임 편입 여부와 -> 같은 축이 아니다. 자세한 composition/cutover 상태는 `src/platforms/messaging/CLAUDE.md`가 소유한다. +> 같은 축이 아니다. 자세한 composition/cutover 상태는 `src/platforms/messaging/AGENTS.md`가 소유한다. ## 브로커 등급 diff --git a/docs/mongodb/consumer-leaf-guide.md b/docs/mongodb/consumer-leaf-guide.md index 9b7dd563..9ca05e57 100644 --- a/docs/mongodb/consumer-leaf-guide.md +++ b/docs/mongodb/consumer-leaf-guide.md @@ -3,7 +3,7 @@ 파생 서비스가 `adapter:outbound:persistence-mongo`를 실제로 쓰려면 **자기 Mongo 어댑터 leaf**를 하나 만든다. 이 leaf(이하 "플랫폼 leaf")는 client·template·정책·실패 분류를 주고, document·repository· mapper·port 구현은 서비스 leaf가 가진다. 플랫폼 leaf에는 예시 도메인을 production으로 넣지 않는다 -(`src/adapter/outbound/persistence-mongo/CLAUDE.md` "Forbidden"). +(`src/adapter/outbound/persistence-mongo/AGENTS.md` "Forbidden"). 전체 흐름: diff --git a/docs/upgrade/2026-11-harness.md b/docs/upgrade/2026-11-harness.md new file mode 100644 index 00000000..8d817540 --- /dev/null +++ b/docs/upgrade/2026-11-harness.md @@ -0,0 +1,14 @@ +# 업그레이드 안내 — 2026-11 Claude Code 작업 환경(하네스) + +- 범위: 지침 파일 배치(leaf 규칙 문서 이름, 루트 `AGENTS.md`·`CLAUDE.md`), `.claude/`의 권한·훅·규칙·스킬·서브에이전트, 예측·실측 장부 +- 근거: 소유자 결정(2026-11-07), design-docs `harness/01-harness-design.md` 13절, `docs/work/reference/decisions.md` 「지침 배치」 + +## 1. 누가 읽나 + +이 템플릿을 받아 도메인을 채운 파생 서비스가 읽는다. 코드·설정·빌드의 동작은 바뀌지 않았다. 바뀐 것은 지침 파일의 자리와 Claude Code 세션 설정이다. + +## 2. 바뀐 것과 할 일 + +| # | 바뀐 것 | 서비스가 할 일 | +| --- | --- | --- | +| 1 | leaf·family 지역 규칙 문서가 `src/**/CLAUDE.md`에서 같은 폴더 `src/**/AGENTS.md`로 옮겨 갔다. 그 폴더 `CLAUDE.md`는 `@AGENTS.md` 한 줄이다 | 서비스가 leaf `CLAUDE.md`를 고쳤다면 merge에서 충돌이 난다. 고친 내용을 같은 폴더 `AGENTS.md`로 옮기고 `CLAUDE.md`는 한 줄로 둔다. 서비스가 새로 만든 leaf도 같은 모양으로 둔다. 서비스 문서·테스트가 `src//CLAUDE.md`의 내용을 읽으면 `AGENTS.md`로 바꾼다(`git grep -n 'CLAUDE\.md' -- docs src`) | diff --git a/docs/work/README.md b/docs/work/README.md index 85ec8261..b16c5eec 100644 --- a/docs/work/README.md +++ b/docs/work/README.md @@ -31,7 +31,7 @@ 1. 기준 커밋을 고정한다. `git rev-parse HEAD`를 산출물과 보고에 적는다. 2. 이미 정한 것을 읽는다: [reference/decisions.md](reference/decisions.md), `docs/reviews/`에서 가장 최근 리뷰 README의 결정·남은 것 절. 정한 것은 다시 묻지 않는다. -3. 소유 leaf를 찾는다. registry의 `source_path`로 정하고, 가장 가까운 `src/**/CLAUDE.md`를 읽는다. +3. 소유 leaf를 찾는다. registry의 `source_path`로 정하고, 가장 가까운 `src/**/AGENTS.md`를 읽는다. 4. 스킬을 고른다. 정본은 `AGENTS.md` 「Superpowers Workflow」다. playbook에 작업별 스킬이 있다. 5. 자기 worktree와 자기 브랜치에서 일한다. 다른 세션과 같은 checkout을 쓰지 않는다. 6. 무거운 실행(Gradle, Docker, 테스트, 게이트)은 [operate.md](operate.md) 「실행 위치」대로 한다. diff --git a/docs/work/docs-writing.md b/docs/work/docs-writing.md index 7d0147bd..fd4d8ae7 100644 --- a/docs/work/docs-writing.md +++ b/docs/work/docs-writing.md @@ -4,7 +4,7 @@ ## 1. 언제 쓰나 -- `docs/work/`, `docs/manual/`, 루트·leaf `CLAUDE.md`, 모듈 README, runbook, 안내 문서를 쓰거나 고칠 때. +- `docs/work/`, `docs/manual/`, 루트·leaf `AGENTS.md`, 모듈 README, runbook, 안내 문서를 쓰거나 고칠 때. - 이것은 아니다. - 리뷰 문서 → [improve.md](improve.md)(리뷰 양식은 [reference/review-criteria.md](reference/review-criteria.md) 10절) - 설계서·ADR → [research-design.md](research-design.md) @@ -28,7 +28,7 @@ ## 4. 절차 1. 독자와 목적을 한 문장으로 쓴다: "<누가> 이 문서만 읽고 <무엇을> 끝낸다". -2. 정본을 찾는다. 규칙이 이미 `AGENTS.md`, registry, leaf `CLAUDE.md`, `docs/web/http-contract.md`, `docs/registries/`에 있으면 다시 쓰지 않고 가리킨다. 정본과 다르면 정본이 맞다. +2. 정본을 찾는다. 규칙이 이미 `AGENTS.md`, registry, leaf `AGENTS.md`, `docs/web/http-contract.md`, `docs/registries/`에 있으면 다시 쓰지 않고 가리킨다. 정본과 다르면 정본이 맞다. 3. 위치를 정한다. 문서 위치 규칙은 `docs/README.md`다. 여러 repo나 소유자 운영에 걸친 내용은 이 repo가 아니라 design-docs에 둔다. 4. 결론을 먼저 쓴다. 한 문장에 개념 하나, 처음 나온 용어는 그 자리에서 한 줄로 푼다. 흐름이 있으면 화살표 도식을 먼저 둔다. 표는 둘 이상을 비교할 때만 쓴다. 5. 절차는 한 줄에 한 단계, 동사로 시작한다. 명령은 실제로 있는 것만 쓴다. 태스크 이름은 `src/build.gradle`이나 leaf `build.gradle`에서, 경로는 `ls`로 확인한다. diff --git a/docs/work/improve.md b/docs/work/improve.md index 5918448e..21a75b94 100644 --- a/docs/work/improve.md +++ b/docs/work/improve.md @@ -69,7 +69,7 @@ ### 4.3 리팩터링, 성능, 구조, 테스트 구조 - 리팩터링: 지킬 동작·타입·실패·진단을 "보존 조건"으로 적는다. 그 조건을 지키는 테스트가 지금 통과하는지 먼저 본다. 리팩터링과 동작 변경을 한 커밋에 섞지 않는다. -- 복사본을 합칠 때: 정본 하나를 정하고 나머지를 지운다. 못 지우면 이유를 가까운 `CLAUDE.md`에 적고, 두 벌이 같은지 보는 대조 테스트를 둔다. +- 복사본을 합칠 때: 정본 하나를 정하고 나머지를 지운다. 못 지우면 이유를 가까운 `AGENTS.md`에 적고, 두 벌이 같은지 보는 대조 테스트를 둔다. - 성능: 숫자 없이 시작하지 않는다. 기준선 측정 → 원인 좁히기 → 변경 하나 → 같은 조건으로 재측정 → 회귀 테스트로 고정. 조건은 review-criteria.md 「성능 측정」, 지난 기준선은 [evidence.md](evidence.md)다. 지난 숫자는 현재 커밋에서 다시 잰다. - 구조 변경: 설계서(`docs/design/`)와 계획서(`docs/history/plans/`)를 먼저 둔다. review-criteria.md 「leaf 변경 체크리스트」를 따른다. ArchUnit 규칙을 바꾸면 잡혀야 할 위반 fixture와 통과해야 할 허용 fixture를 둘 다 둔다. - 테스트 구조: 지금 테스트가 증명하는 것(이름, 단언, skip 수)을 적는다. 고친 뒤 지키려는 production 코드를 일부러 망가뜨려 테스트가 실패하는지(변이) 본다. 옮겼으면 lane별 테스트 수를 전후로 비교한다. diff --git a/docs/work/new-feature.md b/docs/work/new-feature.md index de926738..1bb3aa2f 100644 --- a/docs/work/new-feature.md +++ b/docs/work/new-feature.md @@ -29,7 +29,7 @@ ## 4. 절차 1. `docs/manual/README.md`를 읽는다. 처음이면 01 → 02 → 03장을 읽는다. -2. 배치를 정한다(`docs/manual/03-placement.md`). 기본은 계층 leaf 안 `` 패키지다. 이름이 템플릿 패키지(`src/application-core/CLAUDE.md` 「Package ownership」)와 겹치지 않는지 본다. +2. 배치를 정한다(`docs/manual/03-placement.md`). 기본은 계층 leaf 안 `` 패키지다. 이름이 템플릿 패키지(`src/application-core/AGENTS.md` 「Package ownership」)와 겹치지 않는지 본다. 3. capability 모듈이면 `docs/manual/10-capabilities.md`와 `AGENTS.md` 「부가 기능(capability) 모듈 규칙」의 완료 기준 7개를 먼저 읽는다. 새 leaf가 생기면 [reference/review-criteria.md](reference/review-criteria.md) 「leaf 변경 체크리스트」를 따른다. 4. 뼈대를 만든다: `scripts/new-feature.sh `(`docs/manual/01-generator.md`). 이 명령은 끝에 Gradle `spotlessApply`를 돈다. 노트북에서는 `--no-format`으로 파일만 만들고, 포맷은 desktop에서 `./gradlew spotlessApply`로 한다([operate.md](operate.md) 「실행 위치」). 5. `docs/manual/02-new-feature.md`의 순서대로 채운다: domain-core → application-core → outbound adapter → inbound adapter → app-bootstrap 조립. 안쪽부터 만들면 각 단계가 앞 단계만 보고 컴파일된다. diff --git a/docs/work/reference/defect-patterns.md b/docs/work/reference/defect-patterns.md index d53b87d7..2052e1bb 100644 --- a/docs/work/reference/defect-patterns.md +++ b/docs/work/reference/defect-patterns.md @@ -2,7 +2,7 @@ 이 repo의 리뷰에서 반복해서 나온 결함을 **모양**으로 묶은 목록이다. 리뷰를 시작하기 전에 훑어보고, 고칠 때는 「막는 기준」을 따른다. 리뷰 README의 「반복되는 원인」에 이 번호(A1~)를 붙인다. 패턴마다 근거가 된 지난 발견은 [evidence.md](../evidence.md) 「결함 패턴의 근거」에 있다. -계층·경계 규칙 자체의 정본은 `AGENTS.md`(HARD-STOP, 모듈 책임, 금지된 지름길)와 가장 가까운 `src/**/CLAUDE.md`다. 이 문서는 그 규칙을 다시 쓰지 않고, 고치거나 리뷰할 때 반복해서 틀린 곳만 적는다. +계층·경계 규칙 자체의 정본은 `AGENTS.md`(HARD-STOP, 모듈 책임, 금지된 지름길)와 가장 가까운 `src/**/AGENTS.md`다. 이 문서는 그 규칙을 다시 쓰지 않고, 고치거나 리뷰할 때 반복해서 틀린 곳만 적는다. ## 패턴 @@ -121,7 +121,7 @@ | 규칙을 일부러 다르게 둔 타입 | 그 타입의 Javadoc | | 정적 분석 제외 | 제외 항목 옆 이유(`src/config/spotbugs/exclude-test.xml` 등) | | 규칙의 예외 경로 | 이유를 요구하는 표시(`@SystemCaller(reason)`) | -| 복사본을 남긴 이유 | 가까운 `CLAUDE.md`(예: `src/platforms/messaging/CLAUDE.md`) | +| 복사본을 남긴 이유 | 가까운 `AGENTS.md`(예: `src/platforms/messaging/AGENTS.md`) | | 되돌리기 비싼 선택 | `docs/adr/ADR-<영역>-<번호>-<제목>.md` | ## 패턴을 더하는 법 diff --git a/docs/work/reference/review-criteria.md b/docs/work/reference/review-criteria.md index 4db104b6..ca26ce51 100644 --- a/docs/work/reference/review-criteria.md +++ b/docs/work/reference/review-criteria.md @@ -101,7 +101,7 @@ | # | 관점 | 볼 곳 | 이런 증거면 결함 | | --- | --- | --- | --- | | 1 | 코드 성숙도 | 바뀐 클래스와 호출자, 예외 경로 | 이름·Javadoc과 다른 동작, 항상 참·거짓인 조건 | -| 2 | 구조적 성숙도 | registry `allowed_dependencies`, ArchUnit, leaf `CLAUDE.md` | HARD-STOP 위반, registry 밖 leaf 디렉터리, 템플릿 패키지가 기능 패키지를 import | +| 2 | 구조적 성숙도 | registry `allowed_dependencies`, ArchUnit, leaf `AGENTS.md` | HARD-STOP 위반, registry 밖 leaf 디렉터리, 템플릿 패키지가 기능 패키지를 import | | 3 | 변경 용이성 | 기능 하나를 더하거나 뺄 때 고칠 파일, `scripts/new-feature.sh` 왕복 | 같은 규칙을 여러 곳에서 바꿔야 함 | | 4 | 인지 부하 | 따라 할 예시 수, 같은 질문에 답하는 문서 수 | 예시·규칙이 여러 갈래이고 고르는 기준이 없음 | | 5 | 위험 가시성 | 기본값, 설정 검증, 기동 rule, 프로필 허용 목록 | 위험이 기본값 뒤에 숨음, 레지스트리 `required`인데 코드는 빈 값 허용 | @@ -123,9 +123,9 @@ | 21 | Guardrail 성숙도 | ArchUnit, `verifyStrictLaneStages`, 기동 rule, 정적 분석 단계 | 거짓으로 통과하는 게이트, 어떤 단계도 돌리지 않는 검사 | | 22 | 추상화 성숙도 | 포트·SPI가 보호하는 것 | adapter가 정책을 소유, 역할 없는 단계 | | 23 | 일관성 | 같은 역할의 이름·모양·규칙 | 같은 개념이 여러 벌 | -| 24 | 네이밍·의미 | `src/application-core/CLAUDE.md` 「Naming convention」, `NamingConventionTest` | 이름과 내용이 다름 | +| 24 | 네이밍·의미 | `src/application-core/AGENTS.md` 「Naming convention」, `NamingConventionTest` | 이름과 내용이 다름 | | 25 | 조직 확장성 | 파생 서비스가 upstream을 받을 때 겹치는 곳 | 기능 패키지가 템플릿 패키지와 섞임 | -| 26 | Ownership | leaf마다 가까운 `CLAUDE.md`·README | 안내 문서 없음, 패키지가 평평해 소유가 안 보임 | +| 26 | Ownership | leaf마다 가까운 `AGENTS.md`·README | 안내 문서 없음, 패키지가 평평해 소유가 안 보임 | | 27 | 삭제 가능성 | capability `runtimeOnly` 한 줄 제거 | 한 줄 지워도 흔적이 남음, bootstrap이 capability 이름을 앎 | | 28 | 회복 가능성 | runbook SQL, DEAD·park, ledger 회수 | 영구히 막히는 key, 복구가 행마다 수작업 | @@ -199,7 +199,7 @@ RED가 증거가 되려면: 실패 메시지가 그 결함을 말한다. 머신 - 모듈 구조는 디렉터리가 아니라 registry가 정한다. 폴더를 바꾸는 일은 registry를 바꾸는 일이다. - 문서는 leaf 목록·개수·leaf별 명령을 적지 않는다. leaf 명령은 registry의 `gradle_path`에서 만든다. - 새 업무 기능은 계층 leaf 안의 패키지가 기본이다(`docs/manual/03-placement.md`). -- 템플릿 패키지 목록은 `src/application-core/CLAUDE.md` 「Package ownership」 표 하나가 정본이다. 템플릿에 패키지를 더하면 같은 변경에서 표에 넣는다. +- 템플릿 패키지 목록은 `src/application-core/AGENTS.md` 「Package ownership」 표 하나가 정본이다. 템플릿에 패키지를 더하면 같은 변경에서 표에 넣는다. - capability는 자기 `AutoConfiguration.imports`로 켜진다. `app-bootstrap`은 capability 이름·스위치 목록·scan 정규식을 갖지 않는다. - vendored family(`messaging:*`, 같은 방식의 `grpc:*`)는 `domain-core`·`application-core`·`shared-contract`에 의존하지 않는다. 그래서 남는 복사본은 이유를 family `CLAUDE.md`에 적고, 값이 같아야 하면 대조 테스트를 둔다. - source set은 runtime·classpath·외부 인프라·JVM 옵션·실행 비용 중 하나가 다를 때만 나눈다. 공유 테스트 코드는 `src/testFixtures/java`다(`docs/adr/ADR-BUILD-001-one-convention-for-shared-test-code.md`). @@ -212,7 +212,7 @@ leaf를 더하거나 옮기거나 지울 때 같은 변경에서 함께 바꾼 - [ ] leaf `build.gradle`: `ca.java-library`·`ca.spring-library`·`ca.platform-module` 중 하나 - [ ] lockfile(`verifyDependencyLocks`가 통과하게 다시 만든다) - [ ] capability면 `src/app-bootstrap/build.gradle`의 `runtimeOnly` 한 줄과 자기 `AutoConfiguration.imports` -- [ ] leaf `CLAUDE.md`, capability면 README 세 가지(제공하는 것, 추가할 한 줄, 필요한 env 키) +- [ ] leaf `AGENTS.md`, capability면 README 세 가지(제공하는 것, 추가할 한 줄, 필요한 env 키) - [ ] 템플릿 패키지를 더하거나 지우면 「Package ownership」 표 - [ ] ArchUnit 규칙과 그 위반·허용 fixture - [ ] 지운 leaf를 가리키던 문서·workflow·주석(grep으로 찾는다) diff --git a/docs/work/research-design.md b/docs/work/research-design.md index 406489b5..45d9e832 100644 --- a/docs/work/research-design.md +++ b/docs/work/research-design.md @@ -26,7 +26,7 @@ - `docs/reviews/`의 리뷰 README 「결정」 절과 영역 문서의 「Declined to judge」 - `docs/adr/`(되돌리기 비싼 선택), `docs/design/`(설계서), `docs/history/plans/`(계획서) - `git log --oneline -- <경로>`와 커밋 본문의 "고른 방법과 버린 대안" - - 가장 가까운 `src/**/CLAUDE.md`와 모듈 README + - 가장 가까운 `src/**/AGENTS.md`와 모듈 README - 외부 선례: 쓰는 라이브러리의 공식 문서와 릴리스 노트(Spring Boot, Flyway, Hibernate 등), 같은 문제를 다룬 공개 저장소. 직접 쓴 글(1차)인지 정리한 글(2차)인지 표시한다. - 스킬: `superpowers:brainstorming`, 결정 기록은 `documentation-and-adrs`, 공식 문서 확인은 `source-driven-development`. 큰 판단은 `doubt-driven-development`로 반론을 세운다. diff --git a/scripts/check-docs.py b/scripts/check-docs.py index cb5628f3..f646ff36 100755 --- a/scripts/check-docs.py +++ b/scripts/check-docs.py @@ -61,7 +61,7 @@ from pathlib import Path REPO_ROOT = Path(__file__).resolve().parent.parent EXCEPTIONS_FILE = "scripts/check-docs-exceptions.txt" REGISTRY_FILE = "src/config/architecture/modules.json" -CHECKS = ("language", "head", "reference", "number", "map", "readme") +CHECKS = ("language", "head", "reference", "number", "map", "readme", "link") # 기록: 본문은 쓴 때의 원문이다. 머리 블록만 고친다. 종류는 폴더가 정한다. RECORD_KINDS = [ @@ -148,6 +148,10 @@ VERSION = re.compile(r"(? list[tuple[int, str]]: return spans +def link_targets(lines: list[str]) -> list[tuple[int, str]]: + """(줄 번호, 상대 링크 대상) — 코드 블록·인라인 코드·「이력」 인용 블록 밖에서만.""" + targets, fence, history = [], None, False + for number, line in enumerate(lines, start=1): + match = FENCE.match(line) + if fence: + if match and match.group(1)[0] == fence[0] and len(match.group(1)) >= len(fence): + fence = None + continue + if match: + fence = match.group(1) + continue + quoted = line.lstrip().startswith(">") + if quoted and HISTORY_QUOTE.match(line): + history = True + elif not quoted: + history = False + if history: + continue + for found in LINK_TARGET.finditer(INLINE.sub("", line)): + target = found.group(1).split("#", 1)[0] + if target and not URL_SCHEME.match(target): + targets.append((number, target)) + return targets + + +def check_link(root: Path, files: list[str]) -> list[Problem]: + known = known_paths(root) + problems = [] + for path in files: + if not is_living(path): + continue + text = (root / path).read_text(encoding="utf-8") + lines = body_lines(text) + offset = len(text.split("\n")) - len(lines) + for number, target in link_targets(lines): + resolved = posixpath.normpath(posixpath.join(posixpath.dirname(path), target)) + if resolved.startswith("..") or not is_known(known, resolved): + problems.append(Problem("link", path, target, f"없는 곳을 가리키는 상대 링크다: {target}", + number + offset)) + return problems + + def registry_projects(root: Path) -> set[str]: registry = root / REGISTRY_FILE if not registry.is_file(): @@ -634,7 +681,7 @@ def check_readme(root: Path, files: list[str]) -> list[Problem]: RUNNERS = {"language": check_language, "head": check_head, "reference": check_reference, "number": check_number, - "map": check_map, "readme": check_readme} + "map": check_map, "readme": check_readme, "link": check_link} def read_exceptions(text: str) -> list[str]: diff --git a/scripts/check-work-docs.py b/scripts/check-work-docs.py index da225c80..c2729a99 100755 --- a/scripts/check-work-docs.py +++ b/scripts/check-work-docs.py @@ -9,7 +9,7 @@ to finish the job from those alone. Two things break that, and both are mechanic who does not know that review. History belongs in `docs/work/evidence.md`, and the two reference files that are indexes of history (`reference/decisions.md`, `reference/defect-patterns.md`). The same rule covers the other files a new session reads first: the rule book `AGENTS.md` and - every `src/**/CLAUDE.md` (owner decision 2026-11-07). Module READMEs, design documents and + every `src/**/AGENTS.md` (owner decision 2026-11-07). Module READMEs, design documents and `docs/reviews/**` keep their IDs, because a reader can follow them from inside the repository. 2. Length. Each entry file has a line limit, and the entry path (map + README + one playbook) has a total limit, so a session reads the whole path instead of skimming it. @@ -196,11 +196,12 @@ def check_skeleton(errors: list[str]) -> None: def module_guides() -> list[Path]: - """Every src/**/CLAUDE.md, the local rule book of a leaf or a family, outside build output.""" + """Every src/**/AGENTS.md, the local rule book of a leaf or a family, outside build output. + The src/**/CLAUDE.md beside it is one line, `@AGENTS.md`, so Claude Code reads the same book.""" skipped = {"build", ".gradle", "node_modules"} return sorted( path - for path in (REPO_ROOT / "src").rglob("CLAUDE.md") + for path in (REPO_ROOT / "src").rglob("AGENTS.md") if not skipped.intersection(path.relative_to(REPO_ROOT).parts) ) diff --git a/scripts/tests/test_check_docs.py b/scripts/tests/test_check_docs.py index 2924849e..17dd28d0 100644 --- a/scripts/tests/test_check_docs.py +++ b/scripts/tests/test_check_docs.py @@ -439,6 +439,38 @@ class ReadmeTest(RepositoryTestCase): self.assertFailsWith(self.repo.run(("readme",)), "루트 README가 없다") +class LinkTest(RepositoryTestCase): + def errors_for(self, text: str, path: str = "src/app/AGENTS.md") -> list[str]: + self.repo.write(path, KOREAN + text) + return self.repo.run(("link",)) + + def test_a_relative_link_to_a_missing_file_fails(self) -> None: + self.assertFailsWith(self.errors_for("[설계](README.md)를 본다.\n"), "없는 곳을 가리키는 상대 링크다: README.md") + + def test_a_relative_link_to_a_tracked_file_passes(self) -> None: + self.repo.write("src/app/README.md", KOREAN) + self.assertEqual(self.errors_for("[설계](README.md#결정)를 본다.\n"), []) + + def test_a_link_up_the_tree_resolves_from_the_document_folder(self) -> None: + self.assertEqual(self.errors_for("[살아 있는 문서](../../docs/live.md)를 본다.\n"), []) + + def test_a_link_out_of_the_repository_fails(self) -> None: + self.assertFailsWith(self.errors_for("[밖](../../../outside.md)를 본다.\n"), "../../../outside.md") + + def test_a_folder_left_empty_on_disk_fails(self) -> None: + (self.repo.root / "src/app/moved").mkdir(parents=True) + self.assertFailsWith(self.errors_for("[옮김](moved/)을 본다.\n"), "moved/") + + def test_urls_anchors_code_and_history_quotes_are_skipped(self) -> None: + text = ("[웹](https://example.com/x) [절](#절) `[코드](gone.md)`\n" + "```text\n[블록](gone.md)\n```\n> 이력: [옛 문서](gone.md)는 지웠다.\n") + self.assertEqual(self.errors_for(text), []) + + def test_a_record_is_not_checked(self) -> None: + self.repo.write("docs/design/2026-08-11-x-design.md", head() + "[옛](gone.md)\n") + self.assertEqual(self.repo.run(("link",)), []) + + class CommandLineTest(unittest.TestCase): def test_an_unknown_check_is_a_usage_error(self) -> None: self.assertEqual(check_docs.main(["--only", "spelling"]), 2) diff --git a/src/README.md b/src/README.md index 7db03a60..a29728d9 100644 --- a/src/README.md +++ b/src/README.md @@ -1,7 +1,7 @@ # src — 빌드 스크립트 / 환경 변수 참조 `src/` 는 Gradle 멀티모듈 루트다. 모듈 경계·의존 방향 규칙은 루트 [CLAUDE.md](../CLAUDE.md) -와 [AGENTS.md](../AGENTS.md), 모듈별 규칙은 각 모듈의 `CLAUDE.md` 가 SSOT이다. +와 [AGENTS.md](../AGENTS.md), 모듈별 규칙은 각 모듈의 `AGENTS.md` 가 SSOT이다. 이 문서는 [build.gradle](build.gradle) 과 [.env.example](.env.example)(복사해 `.env` 로 씀) 의 코드 주석에서 덜어낸 **설정 항목 설명과 결정 근거**를 모아둔 참조용 기록이다. 두 파일에는 짧은 기능 주석과 "자세한 내용은 README 참조" diff --git a/src/adapter/inbound/graphql/AGENTS.md b/src/adapter/inbound/graphql/AGENTS.md new file mode 100644 index 00000000..bec9db91 --- /dev/null +++ b/src/adapter/inbound/graphql/AGENTS.md @@ -0,0 +1,218 @@ +# adapter:inbound:graphql — inbound GraphQL 어댑터(골격 장치) + +## 등록 정보 + +- 모듈 ID: `adapter-inbound-graphql` +- Gradle 경로: `:adapter:inbound:graphql` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:inbound:graphql:test --console=plain` +- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. +- registry 정본: `src/config/architecture/modules.json`. + +Package root: `dev.caskeleton.adapter.inbound.graphql`. + +코드 주석에서 덜어낸 **설계 결정의 근거**는 [README.md](README.md) 가 모아둔다 (이 문서는 모듈 +규칙 SSOT). + +## 플랫폼 모듈 = sub-package (Gradle 모듈 아님) + +GraphQL 플랫폼 설계서는 Stable 16개 + Advanced 12개 "모듈"을 말하지만, 이 구현은 그 28개를 이 +leaf 안의 **bounded sub-package** 로 매핑한다(선례: httpclient leaf 가 366개 java 파일을 같은 +방식으로 담는다). GraphQL 표면은 하나의 인바운드 전송 경계이고, 그 내부 분할을 leaf 정체성 +SSOT(`src/config/architecture/modules.json`)까지 밀어올리지 않는다는 선택이다. + +**이는 레지스트리가 닫혀 있어서가 아니다.** `modules.json` 은 확장 가능하며, 실제로 자매 +플랫폼인 messaging 은 **정반대 선택**을 해서 자기 leaf 들을 레지스트리에 개별 등록했다. 개수는 +`modules.json` 이 소유하며 여기서 되풀이하지 않는다 — 산문에 적힌 숫자는 leaf 가 하나 추가되는 순간 +낡는다. 즉 이 레포에는 두 패턴이 공존한다: + +| | 방식 | 경계 강제 | +| --- | --- | --- | +| messaging | 레지스트리에 leaf 등록 | Gradle 의존 게이트 | +| graphql | 단일 leaf 내 sub-package | 아래 ArchUnit 테스트 (전송 경계만) | + +어느 쪽으로 통일할지는 **미결 아키텍처 결정**이다. + +sub-package 사이의 경계(Stable↔Advanced 방향, 모듈 레코드)를 값으로 선언하던 `moduleboundary/` +모델과 부팅 때마다 컨트롤러를 리플렉션으로 검사하던 `architecture/` 는 2026-09-25 에 삭제했다 +(`docs/capability-status.md` 제거 표). 지금 기계가 지키는 것은 전송 경계 두 가지뿐이다 — +`GraphQlTransportBoundaryArchitectureTest`(ArchUnit, 이 leaf 패키지 대상): + +- resolver(`@SchemaMapping` 계열·`@BatchMapping`) 시그니처는 전송 타입만 쓴다. 반환·인자 타입과 + 그 제네릭 인자에 raw `Map`, persistence 매핑 타입(`@Entity`/`@Document`/`@Table` 등, 단순명 + 매칭), domain·outbound adapter·JPA/Hibernate/Spring Data/JDBC/Mongo/AWS/gRPC/Kafka 타입이 + 오면 실패한다. +- raw `DataFetcher` 구현은 `scalar`·`schema`·`execution` 패키지에만 둔다. + +두 규칙 모두 위반 fixture 로 실제로 잡히는지 같은 테스트가 확인한다. `graphqlStableTest` 의 +required-class 검사가 이 테스트가 조용히 사라지는 것을 막는다. + +## 책임 + +- GraphQL 전송 인프라만: 최소 health 스키마(`skeleton.graphqls`) + `HealthGraphqlController`, + 프로토콜 에러 매핑(`error/GraphQlWireErrorMapper`). Spring for GraphQL 이 스키마와 컨트롤러를 + 자동 합성/바인딩하도록 얹는 얇은 계층이다. +- 그 위에 **GraphQL API 실행 플랫폼**(`...graphql` 하위 sub-package 군)이 스키마 계약·전송 + 프로파일·실행 정책·비용 한계·DataLoader·페이지네이션·에러/보안 경계·관측을 + 소유한다. 플랫폼은 여전히 **feature-agnostic** 이며 정책·계약·검증 기계만 제공한다. +- feature-agnostic: `classpath:graphql/**` 스키마와 모든 `@Controller` `@QueryMapping`/ + `@MutationMapping` 을 generic 하게 합성한다. **WorkLog 등 구체 기능을 이름으로 알지 않는다.** +- 있으면 켜진다: 서비스가 `app-bootstrap/build.gradle`에 `runtimeOnly project(':adapter:inbound:graphql')` + 한 줄로 고른다(기본 조립에는 없다). `APP_GRAPHQL_ENABLED=false`(`app.graphql.enabled`)만 끄며, + 그때 `GraphQlActivationEnvironmentPostProcessor`가 Spring GraphQL 자동 설정도 exclude 한다. + 실제 활성화 시 composition root 는 인증/인가·CORS 정책과 GraphiQL/introspection 운영 설정을 함께 + 명시해야 한다. + +## 오류 코드 소유 + +`docs/registries/error-codes.yaml`은 골격 전체의 `OperationalError` 정본이다. 전송 계층마다 다른 표현 +코드를 모두 받는 registry가 아니다. 그래서 GraphQL은 자기의 유한한 플랫폼 wire 코드 catalog를 +`GraphQlErrorCode`에 둔다. + +- GraphQL 플랫폼 mapper는 `GraphQlErrorCode.platform(...)`을 써야 한다. 등록되지 않은 플랫폼 코드는 바로 + 실패한다. +- application·domain `ApiErrorCode` 값은 별도 namespace로 남고 `GraphQlErrorCode.of(...)`로 그대로 지나간다. + GraphQL은 제품 오류의 이름을 바꾸면 안 된다. 이 길로 wire에 닿는 것은 등록된 `ApiErrorCode`뿐이다 — + DataLoader의 키별 실패도 그것을 싣고, 자유 문자열을 싣지 않는다(소유자 결정 2026-09-25). +- GraphQL이 가진 새 플랫폼 코드는 `GRAPHQL_` 접두어를 쓴다. 접두어 없는 기존 플랫폼 값은 얼려 둔 옛 wire + 계약이고 `legacyUnprefixedPlatformCodes()`가 하나씩 적는다. +- 모델만 있는 capability 코드는 그 capability가 출하하는 요청 경로에 닿기 전까지 `platformCodes()`에 + 더하지 않는다. + +`GraphQlErrorCodeCatalogTest`가 출하하는 catalog 전체, 접두어 규칙, application·플랫폼 namespace 분리를 +고정한다. + +## 허용 + +- `:application-core`, `:domain-core`, `:shared-contract`. `:application-core` 는 선언만이 아니라 실제 + 의존이다 — object 인가의 **답하는 계약**(`dev.caskeleton.application.security.ObjectAccessPolicy`)이 + 거기 살기 때문이다. 이 leaf 가 그 계약을 소유했다면 application 구현체가 인바운드 전송을 컴파일 + 의존해야 했고, 그건 의존 방향이 뒤집힌다. +- `spring-boot-starter-graphql` (Spring Boot BOM 관리 — 버전 명시 없음). +- test scope 에 한해 `spring-boot-starter-web`(random-port 전송 테스트용), + `spring-boot-starter-security`(HTTP 인증/CORS qualification 용), + `io.micrometer:micrometer-core`(실제 `MeterRegistry` 로 metric label cardinality 를 **측정**). +- `java-test-fixtures` — 계약 스위트·통합 fixture·in-memory 스텁은 `src/testFixtures/java` 가 + 소유하고 production jar 에 들어가지 않는다. +- test scope 에 한해 `archunit-junit5` — 전송 경계 규칙(`GraphQlTransportBoundaryArchitectureTest`). + +**서버는 이 leaf 가 고르지 않는다.** production 파일 중 `org.springframework.web`· +`org.springframework.http` 을 import 하는 것은 **하나도 없다**(servlet API 는 body 상한 필터만 +`compileOnly` 로 쓴다). 서버 선택은 composition root 의 결정이고, `gradle.lockfile` 이 이를 +고정한다(`spring-boot-starter-web`·`spring-webmvc`·`spring-webflux`·`tomcat-embed-*` 전부 +`testCompileClasspath,testRuntimeClasspath` 만). 템플릿은 servlet 단일 스택이라 실행 +프로파일(`execution-profile`)·reactive 런타임 감지·blocking bridge 는 2026-09-25 에 삭제했다. +- `annotationProcessor` 로 `spring-boot-configuration-processor` — `GraphQlPlatformProperties` 가 + `@ConfigurationProperties` 이므로 `ca.spring-config` convention plugin이 주는 패리티 + 게이트가 이 선언을 요구한다. + +## 금지 + +- outbound 어댑터(`:adapter:outbound:*`)에 대한 직접 의존 — 인바운드는 application 아웃바운드 + 포트를 통해서만 persistence/messaging/cache/http 에 닿는다 (ArchUnit + `INBOUND_ADAPTERS_DO_NOT_DEPEND_ON_OUTBOUND_ADAPTERS`, 일반 `..adapter.inbound..` 규칙이 이 + 모듈을 자동 커버 — per-module 규칙 추가 불필요). +- 프로덕션 feature 쿼리/뮤테이션을 스켈레톤에 두는 것 — health 표면만 (web 의 + `HealthcheckController` 와 동일 원칙). feature 스키마/컨트롤러/매퍼는 그 기능을 가진 서비스가 소유한다. +- 모듈별 `yml` — 설정은 프레임워크 `spring.graphql.*` 로 composition-root `application.yml` 에 산다. + +## 오류 대응 (`Category → ErrorType`) + +모든 client 에러는 `error/GraphQlWireErrorMapper` 하나를 거친다 — 전송 interceptor, 실행 전 +pipeline(instrumentation), data fetcher resolver 세 곳이 같은 bean 을 받는다. 순서는 플랫폼 거부 +(예외가 구현한 `error/GraphQlPlatformRejection`) → 실패 자신이 `ApiErrorCarrier`면 그 `ApiErrorCode` → 등록된 +application 매핑(`GraphQlExceptionResolver`) → 원인 사슬의 첫 carrier → `IllegalArgumentException`·인자 binder의 +`BindException`=`BAD_PARAMETER`(2026-11-07 소유자 결정). 등록 매핑이 원인 사슬의 carrier보다 먼저라, 앱이 등록한 +실패는 하위 실패를 원인으로 들어도 등록한 코드로 답한다. 실패 자신이 carrier인 타입은 등록해도 쓰이지 않는다. 어디에도 안 +걸린 예외는 `INTERNAL_ERROR` 로 가려지고, 같은 executionId 로 ERROR 로그 한 줄이 남는다. client 문구는 +shared-contract `ClientErrorMessages`(Category 별 한국어 표), `retryable` 은 코드의 값이다. Category → +wire category/`ErrorType` 표는 mapper 의 `RENDERINGS` 하나뿐이고 [README.md](README.md)에 옮겨 둔다. +DataLoader 키 실패는 등록된 `ApiErrorCode` 만 싣는다(`GraphQlBatchLoadException`, 2026-09-25 소유자 결정). + +## 향후 adopter 의 feature 기여 방법 + +- **스키마**: adopter feature 가 `src/main/resources/graphql/*.graphqls` 를 두면 + `classpath:graphql/**` 병합으로 합칠 수 있다. +- **핸들러**: adopter 가 `@Controller` + `@QueryMapping`/`@MutationMapping` 빈을 등록하면 자동 + 바인딩된다. +- **도메인 예외 매핑**: adopter 는 자신의 `DataFetcherExceptionResolver` 를 추가하거나 + `ApiErrorCarrier` 를 사용해 안정적 코드로 매핑할 수 있다. + +템플릿에는 feature GraphQL schema/controller/resolver 가 없다. 이 leaf 는 +health 스키마만 소유한다. + +## 구현된 플랫폼 범위 — 등급으로 말한다 + +"구현됐다" 는 네 가지 서로 다른 사실을 한 단어로 덮는다. 그래서 capability 마다 아래 등급을 +쓰고, **현재 등급보다 높게 표현하지 않는다.** + +| 등급 | 의미 | +| --- | --- | +| `modelled` | 정책·계약 객체가 있고 단위 테스트가 있다. 요청 경로에는 없다. | +| `wired` | Spring 실행 경로에 연결돼 있고, 실제 endpoint 테스트가 그 사실을 증명한다. | +| `integration-verified` | 실제 외부 시스템(datastore/broker) 과의 통합 증거가 있다. | +| `production-verified` | 실부하·장애 시나리오 증거가 있다. | + +| Capability | 등급 | 증거 | +| --- | --- | --- | +| 실행 파이프라인 / 인가 / cost 예산 | `wired` | `systemTest/runtime/GraphQlPlatformExecutionPathTest` (random-port, 거부 시 resolver 호출 0회) | +| depth/complexity 제한 (`cost/`) | `wired` | 같은 테스트의 depth/alias/complexity 케이스 | +| preparsed document cache (`execution/`) | `wired` | `GraphQlPreparsedDocumentAdapter` + 같은 테스트의 캐시 hit 케이스 | +| 커스텀 scalar (`scalar/`) | `wired` | 같은 테스트의 scalar coercion 케이스 | +| 요청 크기 (`http/`, body limit filter) | `wired` | `runtime/GraphQlPlatformWebInterceptorRequestBoundsTest`(auto-configured interceptor 로 byte·shape·extension 거부), `http/GraphQlRequestBoundsTest` | +| 관측 tag cardinality (`observation/`) | `wired` | `runtime/GraphQlRequestObservationConventionAdapter` 가 Spring 의 `ExecutionRequestObservationConvention` 을 구현해 Boot 의 `GraphQlObservationAutoConfiguration` 이 이 컨벤션을 가져간다. `autoconfigure/GraphQlObservationWiringTest`(프레임워크가 실제로 해석), `runtime/GraphQlRequestObservationConventionAdapterTest`(실제 `MeterRegistry` 에 임의 이름 10,000개 → series 1개) | +| object 인가 (`security/`) | `modelled` | 답하는 계약은 중립 `dev.caskeleton.application.security.ObjectAccessPolicy` 가 소유하고 이 leaf 는 `ApplicationObjectAuthorization` 매핑만 가진다. 실행 경로에 연결하는 configuration 은 없다 | +| DataLoader/batching (`dataloader/`) | `wired` | `runtime/GraphQlBatchLoaderRegistrationTest` (실제 graphql-java 실행 + Spring `BatchLoaderRegistry`, 50 parent → 3 downstream 호출), `dataloader/GraphQlBatchContractTest` | +| 요청 deadline (`maxExecutionTime`) | `wired` | `systemTest/runtime/GraphQlRequestDeadlineTest`(virtual thread: deadline 근처 `REQUEST_TIMEOUT`, 하위 필드 미실행), `GraphQlRequestDeadlineOnRequestThreadTest`(요청 스레드: 느린 resolver 가 끝난 뒤 응답 — 한계). 이미 도는 resolver 는 끊지 않는다(README 「요청 deadline」) | +| per-parent fetch(N+1) 신호 | `wired` | `systemTest/runtime/GraphQlPerParentFetchTest`(일반 `@SchemaMapping` 자식 → WARN 1줄 + `graphql.per.parent.fetch`, registrar 자식 → 조용함). 거부하지 않는다 | +| cursor 서명·connection (`pagination/`), fetch profile (`fetch/`) | 라이브러리 | 요청 경로에 없다. 서비스가 직접 호출한다 — README "라이브러리 API". `autoconfigure/GraphQlPolicyRequestPathTest` 가 auto-configuration 이 codec·key ring 을 만들지 않음을 고정 | +| 실부하·장애 | 미달성 | 증거 없음 | + +여전히 미구현인 것: + +- feature GraphQL schema/resolver — 이 leaf 는 health 표면만 소유한다(변경 없음). +- 실부하 성능/장애 시나리오 증거 — 없다. 시나리오 카탈로그와 릴리스 게이트(`release/`, + `advanced/release/`)와 스키마 호환성 비교기(`compat/`)는 호출하는 곳이 없어 2026-09-25 에 + 삭제했다. +- 실제 datastore 통합 증거 — 없다. +- `advanced/**`(SSE·RSocket·federation·incremental·HTTP GET·persisted operation·subscription + replay 등)는 바인딩되지 않는 feature flag gate 뒤의 모델뿐이어서 2026-09-25 에 삭제했다 + (`docs/capability-status.md` 제거 표). 다시 필요하면 Spring GraphQL/graphql-java SPI 를 구현하는 + 형태로 새로 만든다. + +## 테스트 + +```bash +cd src +./gradlew :adapter:inbound:graphql:test --console=plain +./gradlew :adapter:inbound:graphql:graphqlTransportQualificationTest --console=plain +``` + +테스트 레인: + +```bash +./gradlew :adapter:inbound:graphql:graphqlStableTest --console=plain # GraphQlTransportBoundaryArchitectureTest만, skip 금지 +./gradlew :adapter:inbound:graphql:systemTest --console=plain # 23 tests (실제 HTTP 서버) +``` + +`graphqlStableTest` 는 `GraphQlTransportBoundaryArchitectureTest` 가 실행되지 않거나 skip 되면 +실패한다(`build.gradle` 의 strict lane `requires` + `rejectSkipped`). 같은 클래스는 `test` 에서도 돈다. + +## 아티팩트 게이트 + +```bash +./gradlew :adapter:inbound:graphql:test --tests '*GraphQlProductionClassesTest' --console=plain +./gradlew :adapter:inbound:graphql:verifyGraphQlApiSurface --console=plain +``` + +- `GraphQlProductionClassesTest` — production 클래스에 `testkit`/`InMemory`/`ForTests`/`Fixture`/ + `TestContext` 가 하나라도 있으면 실패한다(`test` 의 일부). 테스트용 request context 헬퍼(`testkit/GraphQlRequestContexts`)는 + `src/testFixtures/java` 가 소유한다. +- `verifyGraphQlApiSurface` — `docs/architecture/graphql-api-surface.txt` 스냅샷과 실제 public + 타입 목록이 다르면 실패한다. 단일 jar 안에서 `public` 은 모든 adopter 에게 public 이므로, + 표면 증가는 리뷰 결정이지 빌드 부산물이 아니다. 승인 후: + `./gradlew :adapter:inbound:graphql:updateGraphQlApiSurface -PapproveGraphQlApiSurfaceChange`. + +- mutation 멱등성 — 저장소에 연결된 적 없는 `GraphQlMutationIdempotencyInterceptor`·context· + fingerprint 와 `idempotencyKey` extension 허용을 2026-09-25 에 삭제했다. Stable 기본 + `GraphQlExtensionsPolicy` 는 어떤 extension key 도 허용하지 않는다. 요청 재생 멱등성이 필요하면 + application `IdempotencyExecutor` 를 use case 안에서 쓴다. diff --git a/src/adapter/inbound/graphql/CLAUDE.md b/src/adapter/inbound/graphql/CLAUDE.md index bec9db91..43c994c2 100644 --- a/src/adapter/inbound/graphql/CLAUDE.md +++ b/src/adapter/inbound/graphql/CLAUDE.md @@ -1,218 +1 @@ -# adapter:inbound:graphql — inbound GraphQL 어댑터(골격 장치) - -## 등록 정보 - -- 모듈 ID: `adapter-inbound-graphql` -- Gradle 경로: `:adapter:inbound:graphql` -- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:inbound:graphql:test --console=plain` -- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. -- registry 정본: `src/config/architecture/modules.json`. - -Package root: `dev.caskeleton.adapter.inbound.graphql`. - -코드 주석에서 덜어낸 **설계 결정의 근거**는 [README.md](README.md) 가 모아둔다 (이 문서는 모듈 -규칙 SSOT). - -## 플랫폼 모듈 = sub-package (Gradle 모듈 아님) - -GraphQL 플랫폼 설계서는 Stable 16개 + Advanced 12개 "모듈"을 말하지만, 이 구현은 그 28개를 이 -leaf 안의 **bounded sub-package** 로 매핑한다(선례: httpclient leaf 가 366개 java 파일을 같은 -방식으로 담는다). GraphQL 표면은 하나의 인바운드 전송 경계이고, 그 내부 분할을 leaf 정체성 -SSOT(`src/config/architecture/modules.json`)까지 밀어올리지 않는다는 선택이다. - -**이는 레지스트리가 닫혀 있어서가 아니다.** `modules.json` 은 확장 가능하며, 실제로 자매 -플랫폼인 messaging 은 **정반대 선택**을 해서 자기 leaf 들을 레지스트리에 개별 등록했다. 개수는 -`modules.json` 이 소유하며 여기서 되풀이하지 않는다 — 산문에 적힌 숫자는 leaf 가 하나 추가되는 순간 -낡는다. 즉 이 레포에는 두 패턴이 공존한다: - -| | 방식 | 경계 강제 | -| --- | --- | --- | -| messaging | 레지스트리에 leaf 등록 | Gradle 의존 게이트 | -| graphql | 단일 leaf 내 sub-package | 아래 ArchUnit 테스트 (전송 경계만) | - -어느 쪽으로 통일할지는 **미결 아키텍처 결정**이다. - -sub-package 사이의 경계(Stable↔Advanced 방향, 모듈 레코드)를 값으로 선언하던 `moduleboundary/` -모델과 부팅 때마다 컨트롤러를 리플렉션으로 검사하던 `architecture/` 는 2026-09-25 에 삭제했다 -(`docs/capability-status.md` 제거 표). 지금 기계가 지키는 것은 전송 경계 두 가지뿐이다 — -`GraphQlTransportBoundaryArchitectureTest`(ArchUnit, 이 leaf 패키지 대상): - -- resolver(`@SchemaMapping` 계열·`@BatchMapping`) 시그니처는 전송 타입만 쓴다. 반환·인자 타입과 - 그 제네릭 인자에 raw `Map`, persistence 매핑 타입(`@Entity`/`@Document`/`@Table` 등, 단순명 - 매칭), domain·outbound adapter·JPA/Hibernate/Spring Data/JDBC/Mongo/AWS/gRPC/Kafka 타입이 - 오면 실패한다. -- raw `DataFetcher` 구현은 `scalar`·`schema`·`execution` 패키지에만 둔다. - -두 규칙 모두 위반 fixture 로 실제로 잡히는지 같은 테스트가 확인한다. `graphqlStableTest` 의 -required-class 검사가 이 테스트가 조용히 사라지는 것을 막는다. - -## 책임 - -- GraphQL 전송 인프라만: 최소 health 스키마(`skeleton.graphqls`) + `HealthGraphqlController`, - 프로토콜 에러 매핑(`error/GraphQlWireErrorMapper`). Spring for GraphQL 이 스키마와 컨트롤러를 - 자동 합성/바인딩하도록 얹는 얇은 계층이다. -- 그 위에 **GraphQL API 실행 플랫폼**(`...graphql` 하위 sub-package 군)이 스키마 계약·전송 - 프로파일·실행 정책·비용 한계·DataLoader·페이지네이션·에러/보안 경계·관측을 - 소유한다. 플랫폼은 여전히 **feature-agnostic** 이며 정책·계약·검증 기계만 제공한다. -- feature-agnostic: `classpath:graphql/**` 스키마와 모든 `@Controller` `@QueryMapping`/ - `@MutationMapping` 을 generic 하게 합성한다. **WorkLog 등 구체 기능을 이름으로 알지 않는다.** -- 있으면 켜진다: 서비스가 `app-bootstrap/build.gradle`에 `runtimeOnly project(':adapter:inbound:graphql')` - 한 줄로 고른다(기본 조립에는 없다). `APP_GRAPHQL_ENABLED=false`(`app.graphql.enabled`)만 끄며, - 그때 `GraphQlActivationEnvironmentPostProcessor`가 Spring GraphQL 자동 설정도 exclude 한다. - 실제 활성화 시 composition root 는 인증/인가·CORS 정책과 GraphiQL/introspection 운영 설정을 함께 - 명시해야 한다. - -## 오류 코드 소유 - -`docs/registries/error-codes.yaml`은 골격 전체의 `OperationalError` 정본이다. 전송 계층마다 다른 표현 -코드를 모두 받는 registry가 아니다. 그래서 GraphQL은 자기의 유한한 플랫폼 wire 코드 catalog를 -`GraphQlErrorCode`에 둔다. - -- GraphQL 플랫폼 mapper는 `GraphQlErrorCode.platform(...)`을 써야 한다. 등록되지 않은 플랫폼 코드는 바로 - 실패한다. -- application·domain `ApiErrorCode` 값은 별도 namespace로 남고 `GraphQlErrorCode.of(...)`로 그대로 지나간다. - GraphQL은 제품 오류의 이름을 바꾸면 안 된다. 이 길로 wire에 닿는 것은 등록된 `ApiErrorCode`뿐이다 — - DataLoader의 키별 실패도 그것을 싣고, 자유 문자열을 싣지 않는다(소유자 결정 2026-09-25). -- GraphQL이 가진 새 플랫폼 코드는 `GRAPHQL_` 접두어를 쓴다. 접두어 없는 기존 플랫폼 값은 얼려 둔 옛 wire - 계약이고 `legacyUnprefixedPlatformCodes()`가 하나씩 적는다. -- 모델만 있는 capability 코드는 그 capability가 출하하는 요청 경로에 닿기 전까지 `platformCodes()`에 - 더하지 않는다. - -`GraphQlErrorCodeCatalogTest`가 출하하는 catalog 전체, 접두어 규칙, application·플랫폼 namespace 분리를 -고정한다. - -## 허용 - -- `:application-core`, `:domain-core`, `:shared-contract`. `:application-core` 는 선언만이 아니라 실제 - 의존이다 — object 인가의 **답하는 계약**(`dev.caskeleton.application.security.ObjectAccessPolicy`)이 - 거기 살기 때문이다. 이 leaf 가 그 계약을 소유했다면 application 구현체가 인바운드 전송을 컴파일 - 의존해야 했고, 그건 의존 방향이 뒤집힌다. -- `spring-boot-starter-graphql` (Spring Boot BOM 관리 — 버전 명시 없음). -- test scope 에 한해 `spring-boot-starter-web`(random-port 전송 테스트용), - `spring-boot-starter-security`(HTTP 인증/CORS qualification 용), - `io.micrometer:micrometer-core`(실제 `MeterRegistry` 로 metric label cardinality 를 **측정**). -- `java-test-fixtures` — 계약 스위트·통합 fixture·in-memory 스텁은 `src/testFixtures/java` 가 - 소유하고 production jar 에 들어가지 않는다. -- test scope 에 한해 `archunit-junit5` — 전송 경계 규칙(`GraphQlTransportBoundaryArchitectureTest`). - -**서버는 이 leaf 가 고르지 않는다.** production 파일 중 `org.springframework.web`· -`org.springframework.http` 을 import 하는 것은 **하나도 없다**(servlet API 는 body 상한 필터만 -`compileOnly` 로 쓴다). 서버 선택은 composition root 의 결정이고, `gradle.lockfile` 이 이를 -고정한다(`spring-boot-starter-web`·`spring-webmvc`·`spring-webflux`·`tomcat-embed-*` 전부 -`testCompileClasspath,testRuntimeClasspath` 만). 템플릿은 servlet 단일 스택이라 실행 -프로파일(`execution-profile`)·reactive 런타임 감지·blocking bridge 는 2026-09-25 에 삭제했다. -- `annotationProcessor` 로 `spring-boot-configuration-processor` — `GraphQlPlatformProperties` 가 - `@ConfigurationProperties` 이므로 `ca.spring-config` convention plugin이 주는 패리티 - 게이트가 이 선언을 요구한다. - -## 금지 - -- outbound 어댑터(`:adapter:outbound:*`)에 대한 직접 의존 — 인바운드는 application 아웃바운드 - 포트를 통해서만 persistence/messaging/cache/http 에 닿는다 (ArchUnit - `INBOUND_ADAPTERS_DO_NOT_DEPEND_ON_OUTBOUND_ADAPTERS`, 일반 `..adapter.inbound..` 규칙이 이 - 모듈을 자동 커버 — per-module 규칙 추가 불필요). -- 프로덕션 feature 쿼리/뮤테이션을 스켈레톤에 두는 것 — health 표면만 (web 의 - `HealthcheckController` 와 동일 원칙). feature 스키마/컨트롤러/매퍼는 그 기능을 가진 서비스가 소유한다. -- 모듈별 `yml` — 설정은 프레임워크 `spring.graphql.*` 로 composition-root `application.yml` 에 산다. - -## 오류 대응 (`Category → ErrorType`) - -모든 client 에러는 `error/GraphQlWireErrorMapper` 하나를 거친다 — 전송 interceptor, 실행 전 -pipeline(instrumentation), data fetcher resolver 세 곳이 같은 bean 을 받는다. 순서는 플랫폼 거부 -(예외가 구현한 `error/GraphQlPlatformRejection`) → 실패 자신이 `ApiErrorCarrier`면 그 `ApiErrorCode` → 등록된 -application 매핑(`GraphQlExceptionResolver`) → 원인 사슬의 첫 carrier → `IllegalArgumentException`·인자 binder의 -`BindException`=`BAD_PARAMETER`(2026-11-07 소유자 결정). 등록 매핑이 원인 사슬의 carrier보다 먼저라, 앱이 등록한 -실패는 하위 실패를 원인으로 들어도 등록한 코드로 답한다. 실패 자신이 carrier인 타입은 등록해도 쓰이지 않는다. 어디에도 안 -걸린 예외는 `INTERNAL_ERROR` 로 가려지고, 같은 executionId 로 ERROR 로그 한 줄이 남는다. client 문구는 -shared-contract `ClientErrorMessages`(Category 별 한국어 표), `retryable` 은 코드의 값이다. Category → -wire category/`ErrorType` 표는 mapper 의 `RENDERINGS` 하나뿐이고 [README.md](README.md)에 옮겨 둔다. -DataLoader 키 실패는 등록된 `ApiErrorCode` 만 싣는다(`GraphQlBatchLoadException`, 2026-09-25 소유자 결정). - -## 향후 adopter 의 feature 기여 방법 - -- **스키마**: adopter feature 가 `src/main/resources/graphql/*.graphqls` 를 두면 - `classpath:graphql/**` 병합으로 합칠 수 있다. -- **핸들러**: adopter 가 `@Controller` + `@QueryMapping`/`@MutationMapping` 빈을 등록하면 자동 - 바인딩된다. -- **도메인 예외 매핑**: adopter 는 자신의 `DataFetcherExceptionResolver` 를 추가하거나 - `ApiErrorCarrier` 를 사용해 안정적 코드로 매핑할 수 있다. - -템플릿에는 feature GraphQL schema/controller/resolver 가 없다. 이 leaf 는 -health 스키마만 소유한다. - -## 구현된 플랫폼 범위 — 등급으로 말한다 - -"구현됐다" 는 네 가지 서로 다른 사실을 한 단어로 덮는다. 그래서 capability 마다 아래 등급을 -쓰고, **현재 등급보다 높게 표현하지 않는다.** - -| 등급 | 의미 | -| --- | --- | -| `modelled` | 정책·계약 객체가 있고 단위 테스트가 있다. 요청 경로에는 없다. | -| `wired` | Spring 실행 경로에 연결돼 있고, 실제 endpoint 테스트가 그 사실을 증명한다. | -| `integration-verified` | 실제 외부 시스템(datastore/broker) 과의 통합 증거가 있다. | -| `production-verified` | 실부하·장애 시나리오 증거가 있다. | - -| Capability | 등급 | 증거 | -| --- | --- | --- | -| 실행 파이프라인 / 인가 / cost 예산 | `wired` | `systemTest/runtime/GraphQlPlatformExecutionPathTest` (random-port, 거부 시 resolver 호출 0회) | -| depth/complexity 제한 (`cost/`) | `wired` | 같은 테스트의 depth/alias/complexity 케이스 | -| preparsed document cache (`execution/`) | `wired` | `GraphQlPreparsedDocumentAdapter` + 같은 테스트의 캐시 hit 케이스 | -| 커스텀 scalar (`scalar/`) | `wired` | 같은 테스트의 scalar coercion 케이스 | -| 요청 크기 (`http/`, body limit filter) | `wired` | `runtime/GraphQlPlatformWebInterceptorRequestBoundsTest`(auto-configured interceptor 로 byte·shape·extension 거부), `http/GraphQlRequestBoundsTest` | -| 관측 tag cardinality (`observation/`) | `wired` | `runtime/GraphQlRequestObservationConventionAdapter` 가 Spring 의 `ExecutionRequestObservationConvention` 을 구현해 Boot 의 `GraphQlObservationAutoConfiguration` 이 이 컨벤션을 가져간다. `autoconfigure/GraphQlObservationWiringTest`(프레임워크가 실제로 해석), `runtime/GraphQlRequestObservationConventionAdapterTest`(실제 `MeterRegistry` 에 임의 이름 10,000개 → series 1개) | -| object 인가 (`security/`) | `modelled` | 답하는 계약은 중립 `dev.caskeleton.application.security.ObjectAccessPolicy` 가 소유하고 이 leaf 는 `ApplicationObjectAuthorization` 매핑만 가진다. 실행 경로에 연결하는 configuration 은 없다 | -| DataLoader/batching (`dataloader/`) | `wired` | `runtime/GraphQlBatchLoaderRegistrationTest` (실제 graphql-java 실행 + Spring `BatchLoaderRegistry`, 50 parent → 3 downstream 호출), `dataloader/GraphQlBatchContractTest` | -| 요청 deadline (`maxExecutionTime`) | `wired` | `systemTest/runtime/GraphQlRequestDeadlineTest`(virtual thread: deadline 근처 `REQUEST_TIMEOUT`, 하위 필드 미실행), `GraphQlRequestDeadlineOnRequestThreadTest`(요청 스레드: 느린 resolver 가 끝난 뒤 응답 — 한계). 이미 도는 resolver 는 끊지 않는다(README 「요청 deadline」) | -| per-parent fetch(N+1) 신호 | `wired` | `systemTest/runtime/GraphQlPerParentFetchTest`(일반 `@SchemaMapping` 자식 → WARN 1줄 + `graphql.per.parent.fetch`, registrar 자식 → 조용함). 거부하지 않는다 | -| cursor 서명·connection (`pagination/`), fetch profile (`fetch/`) | 라이브러리 | 요청 경로에 없다. 서비스가 직접 호출한다 — README "라이브러리 API". `autoconfigure/GraphQlPolicyRequestPathTest` 가 auto-configuration 이 codec·key ring 을 만들지 않음을 고정 | -| 실부하·장애 | 미달성 | 증거 없음 | - -여전히 미구현인 것: - -- feature GraphQL schema/resolver — 이 leaf 는 health 표면만 소유한다(변경 없음). -- 실부하 성능/장애 시나리오 증거 — 없다. 시나리오 카탈로그와 릴리스 게이트(`release/`, - `advanced/release/`)와 스키마 호환성 비교기(`compat/`)는 호출하는 곳이 없어 2026-09-25 에 - 삭제했다. -- 실제 datastore 통합 증거 — 없다. -- `advanced/**`(SSE·RSocket·federation·incremental·HTTP GET·persisted operation·subscription - replay 등)는 바인딩되지 않는 feature flag gate 뒤의 모델뿐이어서 2026-09-25 에 삭제했다 - (`docs/capability-status.md` 제거 표). 다시 필요하면 Spring GraphQL/graphql-java SPI 를 구현하는 - 형태로 새로 만든다. - -## 테스트 - -```bash -cd src -./gradlew :adapter:inbound:graphql:test --console=plain -./gradlew :adapter:inbound:graphql:graphqlTransportQualificationTest --console=plain -``` - -테스트 레인: - -```bash -./gradlew :adapter:inbound:graphql:graphqlStableTest --console=plain # GraphQlTransportBoundaryArchitectureTest만, skip 금지 -./gradlew :adapter:inbound:graphql:systemTest --console=plain # 23 tests (실제 HTTP 서버) -``` - -`graphqlStableTest` 는 `GraphQlTransportBoundaryArchitectureTest` 가 실행되지 않거나 skip 되면 -실패한다(`build.gradle` 의 strict lane `requires` + `rejectSkipped`). 같은 클래스는 `test` 에서도 돈다. - -## 아티팩트 게이트 - -```bash -./gradlew :adapter:inbound:graphql:test --tests '*GraphQlProductionClassesTest' --console=plain -./gradlew :adapter:inbound:graphql:verifyGraphQlApiSurface --console=plain -``` - -- `GraphQlProductionClassesTest` — production 클래스에 `testkit`/`InMemory`/`ForTests`/`Fixture`/ - `TestContext` 가 하나라도 있으면 실패한다(`test` 의 일부). 테스트용 request context 헬퍼(`testkit/GraphQlRequestContexts`)는 - `src/testFixtures/java` 가 소유한다. -- `verifyGraphQlApiSurface` — `docs/architecture/graphql-api-surface.txt` 스냅샷과 실제 public - 타입 목록이 다르면 실패한다. 단일 jar 안에서 `public` 은 모든 adopter 에게 public 이므로, - 표면 증가는 리뷰 결정이지 빌드 부산물이 아니다. 승인 후: - `./gradlew :adapter:inbound:graphql:updateGraphQlApiSurface -PapproveGraphQlApiSurfaceChange`. - -- mutation 멱등성 — 저장소에 연결된 적 없는 `GraphQlMutationIdempotencyInterceptor`·context· - fingerprint 와 `idempotencyKey` extension 허용을 2026-09-25 에 삭제했다. Stable 기본 - `GraphQlExtensionsPolicy` 는 어떤 extension key 도 허용하지 않는다. 요청 재생 멱등성이 필요하면 - application `IdempotencyExecutor` 를 use case 안에서 쓴다. +@AGENTS.md diff --git a/src/adapter/inbound/graphql/README.md b/src/adapter/inbound/graphql/README.md index 98e59e89..34399b67 100644 --- a/src/adapter/inbound/graphql/README.md +++ b/src/adapter/inbound/graphql/README.md @@ -4,7 +4,7 @@ `dev.caskeleton.adapter.inbound.graphql`. 허용/금지 의존, 모듈 규칙, 설정 knob, 테스트 명령 같은 **모듈 규칙**은 -[CLAUDE.md](CLAUDE.md) 가 SSOT 다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를 +[AGENTS.md](AGENTS.md) 가 SSOT 다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를 모아둔 참조용 기록이다. --- diff --git a/src/adapter/inbound/grpc/AGENTS.md b/src/adapter/inbound/grpc/AGENTS.md new file mode 100644 index 00000000..9b4ef61f --- /dev/null +++ b/src/adapter/inbound/grpc/AGENTS.md @@ -0,0 +1,115 @@ +# adapter:inbound:grpc — inbound gRPC 어댑터(골격 장치) + +## 등록 정보 + +- 모듈 ID: `adapter-inbound-grpc` +- Gradle 경로: `:adapter:inbound:grpc` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:inbound:grpc:test --console=plain` +- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. +- registry 정본: `src/config/architecture/modules.json`. + +Package root: `dev.caskeleton.adapter.inbound.grpc`. + +코드 주석에서 덜어낸 **설계 결정의 근거**는 [README.md](README.md) 가 모아둔다 (이 문서는 모듈 +규칙 SSOT). + +## 책임 + +- gRPC 전송 인프라만: 서버 수명주기(`GrpcServerRunner`), 타입드 설정(`GrpcServerSettings`), + feature 인증 정책 경계, 프로토콜 에러 매핑(`GrpcStatusMapper` + + `GrpcExceptionHandlingInterceptor`), 그리고 `.proto` 없이도 부팅하는 최소 표면(standard + health, 명시적으로 켠 경우에만 reflection). +- feature-agnostic: 모든 `io.grpc.BindableService` 빈을 generic 하게 등록하며 구체 기능을 + 이름으로 알지 않는다. + +## 허용 + +- `:application-core`, `:domain-core`, `:shared-contract`. +- `io.grpc:*` (grpc-netty-shaded / grpc-protobuf / grpc-stub / grpc-services), + `spring-boot-starter`, `spring-boot-starter-validation`. + +## 금지 + +- outbound 어댑터(`:adapter:outbound:*`)에 대한 직접 의존 — 인바운드는 application 아웃바운드 + 포트를 통해서만 persistence/messaging/cache/http 에 닿는다 (ArchUnit + `INBOUND_ADAPTERS_DO_NOT_DEPEND_ON_OUTBOUND_ADAPTERS`). +- 이 스켈레톤 모듈에서의 `com.google.protobuf` 플러그인 / `.proto` — 향후 도입하는 스키마와 + 서비스는 consuming feature 모듈이 소유한다. +- 프로덕션 feature RPC 를 스켈레톤에 두는 것 — health/reflection 표면만 (web 의 + `HealthcheckController` 와 동일 원칙). + +## 설정 손잡이 (`app.grpc.server.*`) + +타입드 `@ConfigurationProperties` 만 두고, 값은 composition-root `application.yml` 에 산다 +(모듈별 `yml` 없음). prefix가 `app.grpc`가 아니라 `.server`까지인 이유: 바인딩이 +`ignoreUnknownFields = false`라서, 부모 prefix를 쓰면 벤더 starter의 `app.grpc.platform.*` +키가 들어오는 순간 기동이 실패한다(`GrpcSafeActivationTest`). + +| key | default | 의미 | +|---|---|---| +| `enabled` | `true` | 모듈이 있으면 켜진다. `false`면 관련 빈과 listener가 생기지 않는다 | +| `port` | `9090` | 바인딩 TCP 포트. `0` 이면 ephemeral 포트(테스트) | +| `bindAddress` | `127.0.0.1` | P1 insecure listener 바인드. loopback 주소만 허용한다 | +| `allowInsecureLocal` | `false` | local plaintext 위험을 명시적으로 승인하는 개발용 override | +| `reflectionEnabled` | `false` | v1 server reflection 노출을 독립적으로 opt-in 한다 | +| `shutdownGraceSeconds` | `5` | graceful shutdown 전체 예산(초, 0 이상). drain 대기를 포함한다 | +| `shutdownDrainSeconds` | `2` | health NOT_SERVING 뒤 listener 를 열어 둔 채 기다리는 초. `shutdownGraceSeconds` 이하 | +| `maxInboundMessageBytes` | `1048576` | 요청 메시지 상한. 넘으면 `RESOURCE_EXHAUSTED` (플랫폼 `GrpcTransportLimits`와 같은 값) | +| `maxInboundMetadataBytes` | `8192` | 호출당 metadata 상한 (플랫폼과 같은 값) | +| `maxConcurrentCallsPerConnection` | `100` | 연결당 동시 호출(HTTP/2 stream) 상한. 넘친 호출은 클라이언트에서 기다린다 | +| `executorMaxPoolSize` | `32` | feature 호출을 실행하는 고정 스레드 수 (플랫폼 executor 기본값) | +| `executorQueueCapacity` | `256` | 스레드를 기다릴 수 있는 호출 수(1..10000). 넘친 호출은 즉시 `RESOURCE_EXHAUSTED` | +| `defaultDeadline` | `10s` | deadline 없는(또는 더 긴) feature 호출의 서버 deadline. 넘으면 `DEADLINE_EXCEEDED` | +| `keepAliveTime` / `keepAliveTimeout` | `30s` / `10s` | 서버 keep-alive ping 간격 / 응답 대기 (플랫폼 `GrpcServerProfile.stable`) | +| `permitKeepAliveTime` | `30s` | 클라이언트 ping 최소 간격. `keepAliveTime` 이하 | +| `maxConnectionAge` / `maxConnectionAgeGrace` | `30m` / `30s` | 연결 수명과 GOAWAY 뒤 유예 | + +한도 값의 근거·플랫폼과의 대응·포화 동작은 [README.md](README.md) 「서버 한도」 절이 소유한다. +`port`는 0..65535 범위여야 한다. 현재 transport credential은 plaintext뿐이므로 +`enabled=true`는 `allowInsecureLocal=true`와 실제 loopback `bindAddress`가 함께 없으면 +configuration binding/startup 단계에서 실패한다. + +## 이 capability 채택하기 + +gRPC도 **빌드 조립에서 고르는 것**이다. 기본 bootJar에는 이 leaf가 없다. + +1. 쓰는 조립에 `:adapter:inbound:grpc`를 더하고 `config/architecture/modules.json`에 맞는 허용 의존 + edge를 더한다. +2. 설정은 capability 루트로 등록한다. 출하하는 `@ConfigurationPropertiesScan`에 + `dev.caskeleton.adapter.inbound.grpc`를 더하지 않는다. +3. 기능의 `BindableService`와 정확히 하나의 `GrpcAuthenticationPolicy`를 준다. +4. 승격 전에 `./gradlew :adapter:inbound:grpc:test :conditionalTransportQualification`을 돌린다. +5. 고른 런타임 계약에 대한 조립 소유의 설정·env registry 항목이 생기기 전에는 운영 채택이 끝난 것이 아니다. + +**지금 전송의 한계:** P1 서버는 평문이고 일부러 loopback bind만 허용한다. 그래서 같은 프로세스나 같은 +Pod sidecar 통신에만 맞다. 보통 Kubernetes Service를 위해 `0.0.0.0`에 bind할 수 없고, 다른 Pod의 트래픽을 +받을 수 없으며, 클러스터를 향한 gRPC endpoint로 내세우면 안 된다. 클러스터에 노출하려면 미뤄 둔 TLS/mTLS +credential 경로와 따로 검증한 loopback 아닌 bind가 필요하다. + +## Feature 기여 방법 + +현재 저장소에는 feature RPC가 없다. 향후 feature를 도입할 +때는 `.proto`/generated stub/`BindableService`를 해당 feature가 소유하고, 서비스 빈과 정확히 한 +개의 caller-supplied `GrpcAuthenticationPolicy` 빈을 함께 제공한다. 정책이 없거나 여러 개면 +listener 시작이 실패한다. 정책은 `Optional authenticate(Metadata)`이고, 돌려준 +호출자는 gRPC `Context`에 담겨 handler가 `GrpcAuthenticatedCaller.current()`로 읽는다. 정책이 +빈 값·`null`을 반환하거나 예외를 던진 요청은 feature handler에 닿지 +않고 안정적인 `UNAUTHENTICATED` status/code/category로 종료된다. 정책 예외는 예외 타입과 메서드 +이름만 WARN으로 남긴다(메시지는 자격 증명을 담을 수 있어 남기지 않는다). + +## P1 증거와 한계 + +- `GrpcSafeActivationTest`: 기본 비활성, 관련 빈 부재, 설정 검증, feature 인증 정책 필수 조건. +- `GrpcP1BoundaryWireTest`: 실제 loopback ephemeral Netty unary service의 auth 성공/실패, + reflection-off, handler/listener/observer/raw-status 오류 sanitization과 sentinel redaction. + 서버 한도(메시지 크기, 기본 deadline, 연결당 동시 호출, executor 포화)도 같은 wire 에서 검증한다. + +이 증거는 local insecure unary qualification일 뿐 production-ready 근거가 아니다. TLS/mTLS, +external bind, 메서드별 deadline, streaming/backpressure, generated protobuf 호환성은 P2로 남아 있다. + +## 테스트 + +```bash +cd src +./gradlew :adapter:inbound:grpc:test +``` diff --git a/src/adapter/inbound/grpc/CLAUDE.md b/src/adapter/inbound/grpc/CLAUDE.md index 9b4ef61f..43c994c2 100644 --- a/src/adapter/inbound/grpc/CLAUDE.md +++ b/src/adapter/inbound/grpc/CLAUDE.md @@ -1,115 +1 @@ -# adapter:inbound:grpc — inbound gRPC 어댑터(골격 장치) - -## 등록 정보 - -- 모듈 ID: `adapter-inbound-grpc` -- Gradle 경로: `:adapter:inbound:grpc` -- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:inbound:grpc:test --console=plain` -- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. -- registry 정본: `src/config/architecture/modules.json`. - -Package root: `dev.caskeleton.adapter.inbound.grpc`. - -코드 주석에서 덜어낸 **설계 결정의 근거**는 [README.md](README.md) 가 모아둔다 (이 문서는 모듈 -규칙 SSOT). - -## 책임 - -- gRPC 전송 인프라만: 서버 수명주기(`GrpcServerRunner`), 타입드 설정(`GrpcServerSettings`), - feature 인증 정책 경계, 프로토콜 에러 매핑(`GrpcStatusMapper` + - `GrpcExceptionHandlingInterceptor`), 그리고 `.proto` 없이도 부팅하는 최소 표면(standard - health, 명시적으로 켠 경우에만 reflection). -- feature-agnostic: 모든 `io.grpc.BindableService` 빈을 generic 하게 등록하며 구체 기능을 - 이름으로 알지 않는다. - -## 허용 - -- `:application-core`, `:domain-core`, `:shared-contract`. -- `io.grpc:*` (grpc-netty-shaded / grpc-protobuf / grpc-stub / grpc-services), - `spring-boot-starter`, `spring-boot-starter-validation`. - -## 금지 - -- outbound 어댑터(`:adapter:outbound:*`)에 대한 직접 의존 — 인바운드는 application 아웃바운드 - 포트를 통해서만 persistence/messaging/cache/http 에 닿는다 (ArchUnit - `INBOUND_ADAPTERS_DO_NOT_DEPEND_ON_OUTBOUND_ADAPTERS`). -- 이 스켈레톤 모듈에서의 `com.google.protobuf` 플러그인 / `.proto` — 향후 도입하는 스키마와 - 서비스는 consuming feature 모듈이 소유한다. -- 프로덕션 feature RPC 를 스켈레톤에 두는 것 — health/reflection 표면만 (web 의 - `HealthcheckController` 와 동일 원칙). - -## 설정 손잡이 (`app.grpc.server.*`) - -타입드 `@ConfigurationProperties` 만 두고, 값은 composition-root `application.yml` 에 산다 -(모듈별 `yml` 없음). prefix가 `app.grpc`가 아니라 `.server`까지인 이유: 바인딩이 -`ignoreUnknownFields = false`라서, 부모 prefix를 쓰면 벤더 starter의 `app.grpc.platform.*` -키가 들어오는 순간 기동이 실패한다(`GrpcSafeActivationTest`). - -| key | default | 의미 | -|---|---|---| -| `enabled` | `true` | 모듈이 있으면 켜진다. `false`면 관련 빈과 listener가 생기지 않는다 | -| `port` | `9090` | 바인딩 TCP 포트. `0` 이면 ephemeral 포트(테스트) | -| `bindAddress` | `127.0.0.1` | P1 insecure listener 바인드. loopback 주소만 허용한다 | -| `allowInsecureLocal` | `false` | local plaintext 위험을 명시적으로 승인하는 개발용 override | -| `reflectionEnabled` | `false` | v1 server reflection 노출을 독립적으로 opt-in 한다 | -| `shutdownGraceSeconds` | `5` | graceful shutdown 전체 예산(초, 0 이상). drain 대기를 포함한다 | -| `shutdownDrainSeconds` | `2` | health NOT_SERVING 뒤 listener 를 열어 둔 채 기다리는 초. `shutdownGraceSeconds` 이하 | -| `maxInboundMessageBytes` | `1048576` | 요청 메시지 상한. 넘으면 `RESOURCE_EXHAUSTED` (플랫폼 `GrpcTransportLimits`와 같은 값) | -| `maxInboundMetadataBytes` | `8192` | 호출당 metadata 상한 (플랫폼과 같은 값) | -| `maxConcurrentCallsPerConnection` | `100` | 연결당 동시 호출(HTTP/2 stream) 상한. 넘친 호출은 클라이언트에서 기다린다 | -| `executorMaxPoolSize` | `32` | feature 호출을 실행하는 고정 스레드 수 (플랫폼 executor 기본값) | -| `executorQueueCapacity` | `256` | 스레드를 기다릴 수 있는 호출 수(1..10000). 넘친 호출은 즉시 `RESOURCE_EXHAUSTED` | -| `defaultDeadline` | `10s` | deadline 없는(또는 더 긴) feature 호출의 서버 deadline. 넘으면 `DEADLINE_EXCEEDED` | -| `keepAliveTime` / `keepAliveTimeout` | `30s` / `10s` | 서버 keep-alive ping 간격 / 응답 대기 (플랫폼 `GrpcServerProfile.stable`) | -| `permitKeepAliveTime` | `30s` | 클라이언트 ping 최소 간격. `keepAliveTime` 이하 | -| `maxConnectionAge` / `maxConnectionAgeGrace` | `30m` / `30s` | 연결 수명과 GOAWAY 뒤 유예 | - -한도 값의 근거·플랫폼과의 대응·포화 동작은 [README.md](README.md) 「서버 한도」 절이 소유한다. -`port`는 0..65535 범위여야 한다. 현재 transport credential은 plaintext뿐이므로 -`enabled=true`는 `allowInsecureLocal=true`와 실제 loopback `bindAddress`가 함께 없으면 -configuration binding/startup 단계에서 실패한다. - -## 이 capability 채택하기 - -gRPC도 **빌드 조립에서 고르는 것**이다. 기본 bootJar에는 이 leaf가 없다. - -1. 쓰는 조립에 `:adapter:inbound:grpc`를 더하고 `config/architecture/modules.json`에 맞는 허용 의존 - edge를 더한다. -2. 설정은 capability 루트로 등록한다. 출하하는 `@ConfigurationPropertiesScan`에 - `dev.caskeleton.adapter.inbound.grpc`를 더하지 않는다. -3. 기능의 `BindableService`와 정확히 하나의 `GrpcAuthenticationPolicy`를 준다. -4. 승격 전에 `./gradlew :adapter:inbound:grpc:test :conditionalTransportQualification`을 돌린다. -5. 고른 런타임 계약에 대한 조립 소유의 설정·env registry 항목이 생기기 전에는 운영 채택이 끝난 것이 아니다. - -**지금 전송의 한계:** P1 서버는 평문이고 일부러 loopback bind만 허용한다. 그래서 같은 프로세스나 같은 -Pod sidecar 통신에만 맞다. 보통 Kubernetes Service를 위해 `0.0.0.0`에 bind할 수 없고, 다른 Pod의 트래픽을 -받을 수 없으며, 클러스터를 향한 gRPC endpoint로 내세우면 안 된다. 클러스터에 노출하려면 미뤄 둔 TLS/mTLS -credential 경로와 따로 검증한 loopback 아닌 bind가 필요하다. - -## Feature 기여 방법 - -현재 저장소에는 feature RPC가 없다. 향후 feature를 도입할 -때는 `.proto`/generated stub/`BindableService`를 해당 feature가 소유하고, 서비스 빈과 정확히 한 -개의 caller-supplied `GrpcAuthenticationPolicy` 빈을 함께 제공한다. 정책이 없거나 여러 개면 -listener 시작이 실패한다. 정책은 `Optional authenticate(Metadata)`이고, 돌려준 -호출자는 gRPC `Context`에 담겨 handler가 `GrpcAuthenticatedCaller.current()`로 읽는다. 정책이 -빈 값·`null`을 반환하거나 예외를 던진 요청은 feature handler에 닿지 -않고 안정적인 `UNAUTHENTICATED` status/code/category로 종료된다. 정책 예외는 예외 타입과 메서드 -이름만 WARN으로 남긴다(메시지는 자격 증명을 담을 수 있어 남기지 않는다). - -## P1 증거와 한계 - -- `GrpcSafeActivationTest`: 기본 비활성, 관련 빈 부재, 설정 검증, feature 인증 정책 필수 조건. -- `GrpcP1BoundaryWireTest`: 실제 loopback ephemeral Netty unary service의 auth 성공/실패, - reflection-off, handler/listener/observer/raw-status 오류 sanitization과 sentinel redaction. - 서버 한도(메시지 크기, 기본 deadline, 연결당 동시 호출, executor 포화)도 같은 wire 에서 검증한다. - -이 증거는 local insecure unary qualification일 뿐 production-ready 근거가 아니다. TLS/mTLS, -external bind, 메서드별 deadline, streaming/backpressure, generated protobuf 호환성은 P2로 남아 있다. - -## 테스트 - -```bash -cd src -./gradlew :adapter:inbound:grpc:test -``` +@AGENTS.md diff --git a/src/adapter/inbound/grpc/README.md b/src/adapter/inbound/grpc/README.md index 47bd49d8..23e16504 100644 --- a/src/adapter/inbound/grpc/README.md +++ b/src/adapter/inbound/grpc/README.md @@ -4,7 +4,7 @@ `dev.caskeleton.adapter.inbound.grpc`. 허용/금지 의존, 모듈 규칙, 설정 knob, 테스트 명령 같은 **모듈 규칙**은 -[CLAUDE.md](CLAUDE.md) 가 SSOT 다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를 +[AGENTS.md](AGENTS.md) 가 SSOT 다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를 모아둔 참조용 기록이다. --- diff --git a/src/adapter/inbound/messaging/AGENTS.md b/src/adapter/inbound/messaging/AGENTS.md new file mode 100644 index 00000000..e1637a6e --- /dev/null +++ b/src/adapter/inbound/messaging/AGENTS.md @@ -0,0 +1,23 @@ +# adapter:inbound:messaging + +- 모듈 ID `adapter-inbound-messaging`, Gradle 경로 `:adapter:inbound:messaging`. registry 정본: + `src/config/architecture/modules.json`. +- 책임: 들여온 메시징 플랫폼의 애플리케이션 소비 쪽이다 — 플랫폼이 애플리케이션에서 받아야 하는 + inbox 부품(애플리케이션 DataSource 위의 `JdbcInboxRepository`, 그 `PlatformTransactionManager` 위의 + `TransactionRunner`, 자기 Flyway stream `MessagingInboxSchemaStream`인 inbox migration)과 애플리케이션의 + `MessageHandler` 구현들이다. 핸들러 하나는 전달 하나를 유스케이스 호출 하나로 바꾼다. 핸들러는 그 밖에 + 아무것도 등록하지 않는다: 플랫폼이 그 `destination()`과 `schemaVersions()`가 선언한 것을 decode한다. +- 경계: 핸들러에 업무 규칙을 두지 않는다(HARD-STOP 4). 영속 엔티티나 repository가 없다. broker SDK 타입이 + 없다. 허용 edge는 registry 항목에서만 온다. +- 쓰기 유스케이스를 부르는 핸들러는 `@SystemCaller(reason = ...)`이고 `@SystemInvoked` 유스케이스를 직접 + 만든다. 유스케이스는 bean이 아니고, 사용자 전송 계층은 핸들러를 부르지 않는다 + (`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`)만 구현하고, + `Runnable`이나 프로젝트 밖의 다른 타입은 구현하지 않는다(`SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES`). +- 시험: 자동 구성과 inbox 동작을 보는 시험. `./gradlew :adapter:inbound:messaging:check`. + 실제 Kafka + PostgreSQL 재전달 lane은 `messagingInboxRedeliveryIntegrationTest`다(`:integrationCheck`). +- 좌표: group `dev.caskeleton.adapter.inbound`, jar `adapter-inbound-messaging`. 지우지 않는다 — 기본 + group이면 Gradle에게 이 프로젝트와 `:adapter:outbound:messaging`은 같은 모듈이 된다. +- 설계와 버린 대안: `README.md`. diff --git a/src/adapter/inbound/messaging/CLAUDE.md b/src/adapter/inbound/messaging/CLAUDE.md index e1637a6e..43c994c2 100644 --- a/src/adapter/inbound/messaging/CLAUDE.md +++ b/src/adapter/inbound/messaging/CLAUDE.md @@ -1,23 +1 @@ -# adapter:inbound:messaging - -- 모듈 ID `adapter-inbound-messaging`, Gradle 경로 `:adapter:inbound:messaging`. registry 정본: - `src/config/architecture/modules.json`. -- 책임: 들여온 메시징 플랫폼의 애플리케이션 소비 쪽이다 — 플랫폼이 애플리케이션에서 받아야 하는 - inbox 부품(애플리케이션 DataSource 위의 `JdbcInboxRepository`, 그 `PlatformTransactionManager` 위의 - `TransactionRunner`, 자기 Flyway stream `MessagingInboxSchemaStream`인 inbox migration)과 애플리케이션의 - `MessageHandler` 구현들이다. 핸들러 하나는 전달 하나를 유스케이스 호출 하나로 바꾼다. 핸들러는 그 밖에 - 아무것도 등록하지 않는다: 플랫폼이 그 `destination()`과 `schemaVersions()`가 선언한 것을 decode한다. -- 경계: 핸들러에 업무 규칙을 두지 않는다(HARD-STOP 4). 영속 엔티티나 repository가 없다. broker SDK 타입이 - 없다. 허용 edge는 registry 항목에서만 온다. -- 쓰기 유스케이스를 부르는 핸들러는 `@SystemCaller(reason = ...)`이고 `@SystemInvoked` 유스케이스를 직접 - 만든다. 유스케이스는 bean이 아니고, 사용자 전송 계층은 핸들러를 부르지 않는다 - (`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`)만 구현하고, - `Runnable`이나 프로젝트 밖의 다른 타입은 구현하지 않는다(`SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES`). -- 시험: 자동 구성과 inbox 동작을 보는 시험. `./gradlew :adapter:inbound:messaging:check`. - 실제 Kafka + PostgreSQL 재전달 lane은 `messagingInboxRedeliveryIntegrationTest`다(`:integrationCheck`). -- 좌표: group `dev.caskeleton.adapter.inbound`, jar `adapter-inbound-messaging`. 지우지 않는다 — 기본 - group이면 Gradle에게 이 프로젝트와 `:adapter:outbound:messaging`은 같은 모듈이 된다. -- 설계와 버린 대안: `README.md`. +@AGENTS.md diff --git a/src/adapter/inbound/web-advanced/AGENTS.md b/src/adapter/inbound/web-advanced/AGENTS.md new file mode 100644 index 00000000..1f11e209 --- /dev/null +++ b/src/adapter/inbound/web-advanced/AGENTS.md @@ -0,0 +1,45 @@ +# adapter:inbound:web-advanced — 골라 쓰는 web 라이브러리 + +## 등록 정보 + +- 모듈 ID: `adapter-inbound-web-advanced` +- Gradle 경로: `:adapter:inbound:web-advanced` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:inbound:web-advanced:test --console=plain` +- registry 정본: `src/config/architecture/modules.json`. + +패키지 루트: `dev.caskeleton.adapter.inbound.web.advanced`. 무엇을 주는지, 서비스가 더하는 한 줄, +설정은 [README.md](README.md)에 있다. + +## 책임 + +- servlet 운영 경로가 닿지 않는 web 라이브러리 코드: streaming, virtual thread admission, JSON Patch / + Merge Patch, CBOR·XML codec, OpenAPI 3.2 생성기와 breaking change 정책, URI·method 정책, versioning, + operation·budget·contract catalog, security context bridge, 멱등 응답 codec, route 목록. +- 스위치가 있는 MVC capability 셋(virtual thread, NDJSON, JSON sequence). 각각 이 leaf의 + `AutoConfiguration.imports`에 적힌 `@AutoConfiguration`이고 기본은 꺼져 있다. + +## 규칙 + +- 어떤 기본 조립에도 없다. `app-bootstrap` main은 이 leaf에 의존하지 않는다. + `app-bootstrap`은 저장소 전체 ArchUnit import가 이 leaf를 읽도록 `testRuntimeOnly`로만 받는다. +- `adapter:inbound:web`(`core` 어휘)에 의존하고, 그 반대는 없다. +- component scan에 걸리는 stereotype이 없다. 쓰는 애플리케이션은 어댑터 패키지를 scan할 수 있다 + (서비스가 `dev.caskeleton.adapter.inbound.web`을 scan할 수 있다). 그래서 여기 둔 `@Configuration`이나 + `@Component`는 스위치가 무엇을 말하든 만들어진다. 스위치가 있는 배선은 `@AutoConfiguration` + imports + 한 줄이다. import되는 도우미는 stereotype을 달지 않는다(`MvcStreamingSupportConfiguration`). +- 아무 코드도 읽지 않는 설정, 시험만 부르는 `main`의 gate·증거 타입을 두지 않는다 — 릴리스 gate와 + OpenAPI 승격 보고서를 바로 그 이유로 지웠다(`docs/capability-status.md`). +- 기능마다 세대 하나. 운영 web 경로가 이미 다른 방식으로 하는 일을 여기서 다시 구현하지 않는다: + forwarded header(`server.forward-headers-strategy`), CORS·CSRF(`CorsSettings`/`SecurityConfig`), cache + header(`CacheControlFilter`), JSON mapper(Boot의 `JsonMapper`), OpenAPI 손질(`OpenApiContractConfig`). + 그 중복과 WebFlux `functional` 패키지는 2026-09-25에 지웠다(`docs/capability-status.md`). +- `adapter:inbound:web`의 inbound 어댑터 규칙이 그대로 적용된다: repository 접근 없음, 업무 규칙 없음, + `application-core`·`domain-core`로 새는 DTO 없음. + +## 테스트 + +```bash +cd src +./gradlew :adapter:inbound:web-advanced:check --console=plain +./gradlew :adapter:inbound:web-advanced:webAdvancedTest --console=plain +``` diff --git a/src/adapter/inbound/web-advanced/CLAUDE.md b/src/adapter/inbound/web-advanced/CLAUDE.md index 1f11e209..43c994c2 100644 --- a/src/adapter/inbound/web-advanced/CLAUDE.md +++ b/src/adapter/inbound/web-advanced/CLAUDE.md @@ -1,45 +1 @@ -# adapter:inbound:web-advanced — 골라 쓰는 web 라이브러리 - -## 등록 정보 - -- 모듈 ID: `adapter-inbound-web-advanced` -- Gradle 경로: `:adapter:inbound:web-advanced` -- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:inbound:web-advanced:test --console=plain` -- registry 정본: `src/config/architecture/modules.json`. - -패키지 루트: `dev.caskeleton.adapter.inbound.web.advanced`. 무엇을 주는지, 서비스가 더하는 한 줄, -설정은 [README.md](README.md)에 있다. - -## 책임 - -- servlet 운영 경로가 닿지 않는 web 라이브러리 코드: streaming, virtual thread admission, JSON Patch / - Merge Patch, CBOR·XML codec, OpenAPI 3.2 생성기와 breaking change 정책, URI·method 정책, versioning, - operation·budget·contract catalog, security context bridge, 멱등 응답 codec, route 목록. -- 스위치가 있는 MVC capability 셋(virtual thread, NDJSON, JSON sequence). 각각 이 leaf의 - `AutoConfiguration.imports`에 적힌 `@AutoConfiguration`이고 기본은 꺼져 있다. - -## 규칙 - -- 어떤 기본 조립에도 없다. `app-bootstrap` main은 이 leaf에 의존하지 않는다. - `app-bootstrap`은 저장소 전체 ArchUnit import가 이 leaf를 읽도록 `testRuntimeOnly`로만 받는다. -- `adapter:inbound:web`(`core` 어휘)에 의존하고, 그 반대는 없다. -- component scan에 걸리는 stereotype이 없다. 쓰는 애플리케이션은 어댑터 패키지를 scan할 수 있다 - (서비스가 `dev.caskeleton.adapter.inbound.web`을 scan할 수 있다). 그래서 여기 둔 `@Configuration`이나 - `@Component`는 스위치가 무엇을 말하든 만들어진다. 스위치가 있는 배선은 `@AutoConfiguration` + imports - 한 줄이다. import되는 도우미는 stereotype을 달지 않는다(`MvcStreamingSupportConfiguration`). -- 아무 코드도 읽지 않는 설정, 시험만 부르는 `main`의 gate·증거 타입을 두지 않는다 — 릴리스 gate와 - OpenAPI 승격 보고서를 바로 그 이유로 지웠다(`docs/capability-status.md`). -- 기능마다 세대 하나. 운영 web 경로가 이미 다른 방식으로 하는 일을 여기서 다시 구현하지 않는다: - forwarded header(`server.forward-headers-strategy`), CORS·CSRF(`CorsSettings`/`SecurityConfig`), cache - header(`CacheControlFilter`), JSON mapper(Boot의 `JsonMapper`), OpenAPI 손질(`OpenApiContractConfig`). - 그 중복과 WebFlux `functional` 패키지는 2026-09-25에 지웠다(`docs/capability-status.md`). -- `adapter:inbound:web`의 inbound 어댑터 규칙이 그대로 적용된다: repository 접근 없음, 업무 규칙 없음, - `application-core`·`domain-core`로 새는 DTO 없음. - -## 테스트 - -```bash -cd src -./gradlew :adapter:inbound:web-advanced:check --console=plain -./gradlew :adapter:inbound:web-advanced:webAdvancedTest --console=plain -``` +@AGENTS.md diff --git a/src/adapter/inbound/web/AGENTS.md b/src/adapter/inbound/web/AGENTS.md new file mode 100644 index 00000000..50d56f78 --- /dev/null +++ b/src/adapter/inbound/web/AGENTS.md @@ -0,0 +1,172 @@ +# adapter:inbound:web — inbound HTTP 어댑터 + +## 등록 정보 + +- 모듈 ID: `adapter-inbound-web` +- Gradle 경로: `:adapter:inbound:web` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:inbound:web:test --console=plain` +- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. +- registry 정본: `src/config/architecture/modules.json`. + +패키지 루트: `dev.caskeleton.adapter.inbound.web`. + +코드 주석에서 덜어낸 **설계 결정의 근거**는 [README.md](README.md) 가 모아둔다 (이 문서는 모듈 규칙 SSOT). + +## 책임 + +- HTTP controller. +- 요청·응답 DTO. +- 요청 DTO를 application command로 바꾸기. +- 인증, 검증, 오류 대응, filter, web·보안 설정. +- 애플리케이션이 가진 `CorrelationIdPort`로 내놓는, 걸러 낸 요청 correlation 문맥. +- `shared-contract`로 Swagger 의존을 새게 하지 않으면서 `ApiError.details`를 `type: object`로 두는, + 전송 계층이 가진 OpenAPI 손질. + +모든 서비스가 이 leaf를 싣는다. 그래서 servlet 운영 경로가 닿는 것만 담는다: 그 `AutoConfiguration.imports` +루트(`WebAdapterAutoConfiguration`은 envelope, filter, health, rate-limit bean을 import한다. +`WebSecurityAutoConfiguration`은 JWT chain을 import하므로, 자기 보안 방식을 가진 애플리케이션은 그 루트만 +뺀다. `WebMethodSecurityAutoConfiguration`은 method security와 권한 포트를 import하고 chain을 바꿔도 남는다. +이 leaf를 scan하는 쪽은 없다), 그리고 `app-bootstrap`, `web-fileserver`, `composition:fileserver-platform`이 +이름을 대는 타입과 그것이 전이로 참조하는 것. 운영 경로가 닿지 않는 라이브러리 코드(streaming, virtual +thread, patch, codec, OpenAPI 3.2, URI·method 정책, versioning, operation, budget, contract, security context +bridge, `JsonIdempotentResponseCodec`, route 목록)는 골라 쓰는 leaf `adapter:inbound:web-advanced`에 있다. +운영 경로에서 아무도 쓰지 않는 새 타입은 여기가 아니라 거기에 둔다. 이 leaf는 그 leaf에 의존하지 않는다 +(Gradle registry + ArchUnit `WEB-ARCH-ADV`). + +## 허용 + +- `:application-core` +- `:domain-core` +- `:shared-contract` +- `:adapter:outbound:support` — `StrictSettingsBinder`만. `app.security`(`SecuritySettings`, 인증 모드 포함)는 + 모든 모듈이 쓰는 엄격한 binder 하나로 바인딩한다(2026-11-01부터). ArchUnit inbound·outbound 규칙은 그 + leaf에서 이 클래스만 허용한다. +- Spring Web·Security·Validation 의존성. + +## 금지 + +- `adapter:outbound:persistence-jpa`나 다른 `adapter:outbound:*` 타입에 직접 의존하기. +- controller에서 repository나 JPA 엔티티에 직접 접근하기. +- controller, filter, config, mapper, settings 코드 안의 핵심 업무 규칙. +- DTO가 application이나 domain으로 새는 것. + +## 경계 검증과 mapper 계약 + +`feature-boundary-validation-mapping-contract`(설계 기록)가 이 계층 경계의 동작을 정한다. 저장소 단위 +가드레일(ArchUnit + Jackson 설정 + handler)은 정적 위반만 잡는다. 아래 계약은 참조 구현이 따라야 할 런타임 +패턴도 정한다. + +- **B1 — 요청 경계의 Jackson 정책.** `spring.jackson.deserialization`이 `fail-on-unknown-properties`, + `fail-on-null-for-primitives`, `fail-on-ignored-properties`를 `true`로, `read-unknown-enum-values-as-null`을 + `false`로 고정한다. 클래스 수준 `@JsonIgnoreProperties(ignoreUnknown = true)`로 DTO마다 이것을 되돌리지 + **않는다** — ArchUnit 규칙 `REQUEST_DTOS_DO_NOT_SILENCE_UNKNOWN_FIELDS`가 막는다. 요청 record에는 + wrapper 타입(`Integer`, `Long`, `Boolean`, `Optional`)을 써서 JSON `null`이 primitive `0`이 되지 못하게 + 한다. +- **B2 — PATCH 뜻.** RFC 7396 `application/merge-patch+json`(`null = 삭제`)을 쓰지 않는다. PATCH endpoint는 + *없음*(바꾸지 않음), *명시한 null*(필드 비움), *값*(바꿈)을 구별해야 한다. 요청 record에 + `org.openapitools:jackson-databind-nullable`(`JsonNullable`)이나 `Optional` wrapper를 쓴다. +- **B3 — mapper 안의 실패.** record 정규 생성자의 `IllegalArgumentException`, MapStruct가 생성한 NPE, ACL + 정규화 실패 등은 `MappingException`을 던져 대응시킨다. 전역 handler가 그것을 `MAPPING_FAILED`(HTTP 400)로 + 보내고, `BAD_PARAMETER`나 `INTERNAL_ERROR`로 보내지 않는다. mapper가 아닌 호출자의 평범한 + `IllegalArgumentException`은 계속 `BAD_PARAMETER`다. +- **B4 — 검증 층.** 클래스 수준 Bean Validation 제약은 *문법* 층(요청 DTO)에 속한다. 도메인 불변식은 + `application-core` / `domain-core`에 속한다. 문법이 실패하면 `@GroupSequence(...)`로 불변식 평가를 건너뛴다. + `@Valid` cascade 깊이는 3 이하로 둔다. +- **B5 — 다형 역직렬화.** `ObjectMapper.enableDefaultTyping()` / `activateDefaultTyping()`을 부르거나 + `LaissezFaireSubTypeValidator`를 참조하는 것은 CVE-2019-14379 RCE의 입구이고 ArchUnit이 막는다 + (`NO_JACKSON_LAISSEZ_FAIRE_SUBTYPE_VALIDATOR`, `NO_JACKSON_ENABLE_DEFAULT_TYPING_CALL`). sealed `Command` + 타입은 `@JsonTypeInfo(use = NAME)` + `@JsonSubTypes`나 `BasicPolymorphicTypeValidator` 허용 목록을 쓴다. +- **B6 — virtual thread 문맥 전파.** `spring.threads.virtual.enabled=true`이면 `InheritableThreadLocal`을 쓰지 + 않는다(ArchUnit 규칙 `NO_INHERITABLE_THREAD_LOCAL`). filter와 interceptor는 SLF4J 2.0+ MDC나 + `RequestContextHolder`로 `requestId` / `traceId`를 전파한다. +- **B7 — outbound ACL mapper 범위.** outbound HTTP·메시징 어댑터의 응답은 `application-core`나 `domain-core`에 + 닿기 전에 ACL mapper(정규화, 가리기, 공개 필드 고르기)를 거친다 — inbound와 같은 경계 계약이다. 외부 응답 + 원본 타입은 `domain-core`로 새면 안 된다. +- **B8 — bulk endpoint의 부분 성공.** envelope `success = true`는 모든 항목이 성공했을 때뿐이다. 일부가 + 실패하면 `success = false` + `error.code = BATCH_PARTIAL_FAILURE` + `error.details[]`(항목별 배열)로 + 답한다 — 단일 항목 endpoint와 모양이 다르다. 모양이 다르다는 것을 OpenAPI spec에 적는다. + +이 모듈을 쓰는 모듈의 도메인 `@RestControllerAdvice`에는 `@Order(Ordered.HIGHEST_PRECEDENCE)`를 단다(또는 +다른 방법으로 이 모듈의 기본 `GlobalExceptionHandler`보다 앞에 둔다). 그렇지 않으면 기본 handler의 +catch-all `@ExceptionHandler(Exception.class)`가 도메인 예외를 `INTERNAL_ERROR`로 만든다. + +기본 운영 handler(`error/GlobalExceptionHandler`), 오류 코드 계약 +(`dev.caskeleton.shared.error.ApiErrorCode` + `OperationalError`), `error/ErrorResponseFactory`, +`envelope/EnvelopeBodyAdvice`는 이제 운영 모듈(`adapter:inbound:web` / `shared-contract`)에 있어서, 돌아가는 +애플리케이션이 그것을 준다. 기능 전용 예외 handler와 오류 코드는 그 기능을 가진 모듈에 둔다(`docs/manual/06-errors.md`). + +## schema·직렬화 계약 + +`feature-schema-serialization-contract`(설계 기록)가 wire 계약의 *응답을 만드는* 쪽을 정한다 — 위 B1 +*요청을 받는* 정책의 짝이다. 역직렬화 스위치(B1)와 null·빈 값·없음 세 상태(`Patch` + `JsonNullable`, +B2)가 이미 inbound 쪽을 덮고, 아래 규칙이 outbound 쪽을 덮는다. Jackson 속성은 `app-bootstrap`의 +`application.yml`(`spring.jackson.deserialization.*`, `spring.jackson.datatype.*`)에 있다. ArchUnit과 실제 +설정 시험도 `app-bootstrap`에 있다(`JacksonSerializationPolicyTest`, `NO_BIGDECIMAL_DOUBLE_CONSTRUCTOR`). + +- **S1 — 날짜·시간·시간대.** `WRITE_DATES_AS_TIMESTAMPS=false`로 고정하므로 `java.time` 값은 + `JavaTimeModule`을 거쳐 ISO-8601 문자열로 직렬화한다(`OffsetDateTime` → `"...Z"`, `LocalDate` → + `"YYYY-MM-DD"`). 숫자 epoch나 `[y,m,d,...]` 배열이 되지 않는다. 서버 시간대는 **UTC**다: 시각은 `Z` + offset을 가진 `OffsetDateTime`/`Instant`로 낸다. 날짜만 있는 달력 필드에만 `LocalDate`를 쓴다. 시간대 + 없는 `LocalDateTime`을 응답 DTO에 넣지 **않는다** — offset 없이 직렬화되어 계약을 깬다. +- **S2 — 돈·BigDecimal.** 도메인이 따로 적지 않으면 기본 scale 2, 반올림 `HALF_UP`이다(KRW/JPY는 scale 0과 + schema 메모). 값은 지수 표기로 직렬화되지 않는다 — 설정 키로 고정하지 않고 `JacksonSerializationPolicyTest`가 + 큰 값과 끝자리 0을 단언한다. API마다 JSON 표현을 **하나** 고르고 OpenAPI schema에 적는다: 공개·금융 + endpoint는 **string**(`@JsonSerialize(using = ToStringSerializer.class)`. 클라이언트가 파싱하고 정밀도를 + 잃지 않는다), 내부 서비스 사이 endpoint는 **number + plain**. 기본값에 기대지 않는다 — endpoint를 설계할 + 때 정한다. +- **S3 — `new BigDecimal(double)`은 금지다.** `double`/`float` 생성자는 이진 부동소수점 오차를 담는다 + (`new BigDecimal(0.1)` ≠ `0.1`). `String`(`new BigDecimal("0.1")`)이나 `BigDecimal.valueOf(double)`로 + 만든다. ArchUnit 규칙 `NO_BIGDECIMAL_DOUBLE_CONSTRUCTOR`가 강제한다. +- **S4 — enum과 null·빈 값·없음.** 요청 쪽의 모르는 enum → `VALIDATION_FAILED`(B1 + `read-unknown-enum-values-as-null=false`). 옛 값은 명시한 어댑터로 대응시키고 소리 없는 대체값을 쓰지 + 않는다. 없음·명시한 null·값의 구별은 inbound web mapper(Controller DTO → Command)가 가지고 `Patch`(B2)로 + 나타낸다. `domain-core`와 `application-core`는 이미 풀린 세 상태를 받고 wire 타입은 받지 않는다. +- **S5 — 이 브랜치의 범위 밖.** OpenAPI drift 강제는 검증 suite / api-contract-baseline의 몫이다. 지운 + 필드 재사용 금지 도구(`x-removed-fields` 대 markdown catalog)는 `needs-confirmation`이다. outbox·event용 + Avro Schema Registry와 응답 필드 이름 바꾸기·versioning(`feature-api-compatibility-deprecation-contract`)은 + 다른 브랜치다. + +## 업무 규칙 검증 계약 + +`feature-business-rule-validation-contract`(설계 기록)는 **어떤 규칙을 어느 경계에서 검증하는지** 정해서, +「검증」이 controller DTO나 DB 제약 하나로 뭉개지지 않게 한다. 위 경계·대응 계약 위에 놓이고, ArchUnit과 +계약 시험이 강제한다(새 런타임 장치가 아니다). + +| 층 | 소유 | 검증하는 것 | `error.category` | 강제하는 곳 | +|---|---|---|---|---| +| 문법·모양 | `adapter:inbound:web` 요청 DTO(`@Valid` / `jakarta.validation`) | 요청 모양, 타입, 필수 필드 | `VALIDATION` | ArchUnit 규칙 `VALIDATION_CONSTRAINTS_STAY_AT_WEB_BOUNDARY` | +| 유스케이스 정책 | `application-core` | 인가, aggregate를 가로지르는 정책, 상태 전제 조건 | `AUTHZ` / `CONFLICT` | `BusinessRuleValidationContractTest` | +| 도메인 불변식 | `domain-core` 모델·값 객체 **생성자** | 업무 불변식(예: end ≥ start) | `CONFLICT` / `VALIDATION` | 도메인 단위 시험(예: `PeriodTest`) — 생성자가 유일하고 바뀌지 않는 생성 경로다 | +| 영속 무결성 | `adapter:outbound:persistence-jpa`(번역기는 `feature-persistence-failure-baseline`의 것) | unique / FK / check / serialization | `DATA_INTEGRITY` / `CONFLICT` | `BusinessRuleValidationContractTest` + 누출 시험 | + +- **C1 — 검증 애너테이션은 web 경계에 머문다.** `jakarta.validation`(`@NotNull`, `@Valid`, …)은 + `adapter:inbound:web`에만 나와야 한다. `domain-core`와 `application-core`는 불변식과 정책을 평범한 Java로 + 나타낸다. Bean Validation 애너테이션이 `..domain..`이나 `..application..`으로 새면 ArchUnit 규칙 + `VALIDATION_CONSTRAINTS_STAY_AT_WEB_BOUNDARY`가 빌드를 실패시킨다. +- **C2 — 업무 불변식은 도메인에 있고 우회할 수 없다.** 불변식은 값 객체·엔티티 **생성자**(유일한 생성 + 경로)에서 강제하고 타입을 불변으로 둔다. 그래서 어떤 application service나 영속 경로도 불변식을 어긴 + 인스턴스를 내줄 수 없다. DB 제약은 뒷받침일 뿐 유일한 검사가 아니다(금지: 「불변식을 DB 제약으로만 + 지키기」). +- **C3 / C7 — 영속 무결성은 새는 것 없이 운영 오류로 대응한다.** unique·FK·check·serialization 실패는 + **클라이언트에게 안전한 메시지만** 가진 `DATA_INTEGRITY` / `CONFLICT`로 대응한다. SQL 원문, 제약·index + 이름, SQLState 코드, 예외 클래스, stack frame은 `error.message`나 `error.details`에 닿으면 안 된다. 기본 + `GlobalExceptionHandler` catch-all이 이미 메시지를 불투명한 공용 메시지(`ClientErrorMessages.OPAQUE`)로 + 바꾸고 details를 `null`로 낸다. category가 맞는 대응(23505 → `CONFLICT/DB_UNIQUE_VIOLATION`, …)은 + `feature-persistence-failure-baseline`의 영속 어댑터 번역기가 가진다. +- **C8 — 중복 검증에는 정본 소유자가 있어야 한다.** UX나 성능을 위해 같은 규칙을 다른 층에서 미리 검사할 수 + 있다(예: DB unique 제약을 따라 하는 application 사전 검사). 단 그 규칙의 **정본 소유자**를 코드 주석이나 + 관련 `AGENTS.md`에 적어야 한다. 소유자를 적지 않은 중복 검증기는 리뷰에서 실패다(소리 없이 서로 어긋날 + 위험). 자동 규칙이 아니라 절차 게이트(PR 리뷰)다 — 소유자 표지 애너테이션이 정당해질 때까지 + `needs-confirmation`이다. + +이 브랜치의 범위 밖(참조만 하고 여기서 다시 구현하지 않는다): SQLState → 코드 9행 표와 +`DataAccessException` 번역기(`feature-persistence-failure-baseline`), Jackson B1/B2 요청 경계 스위치와 mapper +표지 예외(`feature-boundary-validation-mapping-contract`), envelope, `Category` enum, `OperationalError` 코드 +(`feature-operational-error-observability-foundation`). + +## 테스트 + +```bash +cd src +./gradlew :adapter:inbound:web:test --console=plain +``` diff --git a/src/adapter/inbound/web/CLAUDE.md b/src/adapter/inbound/web/CLAUDE.md index b31212eb..43c994c2 100644 --- a/src/adapter/inbound/web/CLAUDE.md +++ b/src/adapter/inbound/web/CLAUDE.md @@ -1,172 +1 @@ -# adapter:inbound:web — inbound HTTP 어댑터 - -## 등록 정보 - -- 모듈 ID: `adapter-inbound-web` -- Gradle 경로: `:adapter:inbound:web` -- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:inbound:web:test --console=plain` -- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. -- registry 정본: `src/config/architecture/modules.json`. - -패키지 루트: `dev.caskeleton.adapter.inbound.web`. - -코드 주석에서 덜어낸 **설계 결정의 근거**는 [README.md](README.md) 가 모아둔다 (이 문서는 모듈 규칙 SSOT). - -## 책임 - -- HTTP controller. -- 요청·응답 DTO. -- 요청 DTO를 application command로 바꾸기. -- 인증, 검증, 오류 대응, filter, web·보안 설정. -- 애플리케이션이 가진 `CorrelationIdPort`로 내놓는, 걸러 낸 요청 correlation 문맥. -- `shared-contract`로 Swagger 의존을 새게 하지 않으면서 `ApiError.details`를 `type: object`로 두는, - 전송 계층이 가진 OpenAPI 손질. - -모든 서비스가 이 leaf를 싣는다. 그래서 servlet 운영 경로가 닿는 것만 담는다: 그 `AutoConfiguration.imports` -루트(`WebAdapterAutoConfiguration`은 envelope, filter, health, rate-limit bean을 import한다. -`WebSecurityAutoConfiguration`은 JWT chain을 import하므로, 자기 보안 방식을 가진 애플리케이션은 그 루트만 -뺀다. `WebMethodSecurityAutoConfiguration`은 method security와 권한 포트를 import하고 chain을 바꿔도 남는다. -이 leaf를 scan하는 쪽은 없다), 그리고 `app-bootstrap`, `web-fileserver`, `composition:fileserver-platform`이 -이름을 대는 타입과 그것이 전이로 참조하는 것. 운영 경로가 닿지 않는 라이브러리 코드(streaming, virtual -thread, patch, codec, OpenAPI 3.2, URI·method 정책, versioning, operation, budget, contract, security context -bridge, `JsonIdempotentResponseCodec`, route 목록)는 골라 쓰는 leaf `adapter:inbound:web-advanced`에 있다. -운영 경로에서 아무도 쓰지 않는 새 타입은 여기가 아니라 거기에 둔다. 이 leaf는 그 leaf에 의존하지 않는다 -(Gradle registry + ArchUnit `WEB-ARCH-ADV`). - -## 허용 - -- `:application-core` -- `:domain-core` -- `:shared-contract` -- `:adapter:outbound:support` — `StrictSettingsBinder`만. `app.security`(`SecuritySettings`, 인증 모드 포함)는 - 모든 모듈이 쓰는 엄격한 binder 하나로 바인딩한다(2026-11-01부터). ArchUnit inbound·outbound 규칙은 그 - leaf에서 이 클래스만 허용한다. -- Spring Web·Security·Validation 의존성. - -## 금지 - -- `adapter:outbound:persistence-jpa`나 다른 `adapter:outbound:*` 타입에 직접 의존하기. -- controller에서 repository나 JPA 엔티티에 직접 접근하기. -- controller, filter, config, mapper, settings 코드 안의 핵심 업무 규칙. -- DTO가 application이나 domain으로 새는 것. - -## 경계 검증과 mapper 계약 - -`feature-boundary-validation-mapping-contract`(설계 기록)가 이 계층 경계의 동작을 정한다. 저장소 단위 -가드레일(ArchUnit + Jackson 설정 + handler)은 정적 위반만 잡는다. 아래 계약은 참조 구현이 따라야 할 런타임 -패턴도 정한다. - -- **B1 — 요청 경계의 Jackson 정책.** `spring.jackson.deserialization`이 `fail-on-unknown-properties`, - `fail-on-null-for-primitives`, `fail-on-ignored-properties`를 `true`로, `read-unknown-enum-values-as-null`을 - `false`로 고정한다. 클래스 수준 `@JsonIgnoreProperties(ignoreUnknown = true)`로 DTO마다 이것을 되돌리지 - **않는다** — ArchUnit 규칙 `REQUEST_DTOS_DO_NOT_SILENCE_UNKNOWN_FIELDS`가 막는다. 요청 record에는 - wrapper 타입(`Integer`, `Long`, `Boolean`, `Optional`)을 써서 JSON `null`이 primitive `0`이 되지 못하게 - 한다. -- **B2 — PATCH 뜻.** RFC 7396 `application/merge-patch+json`(`null = 삭제`)을 쓰지 않는다. PATCH endpoint는 - *없음*(바꾸지 않음), *명시한 null*(필드 비움), *값*(바꿈)을 구별해야 한다. 요청 record에 - `org.openapitools:jackson-databind-nullable`(`JsonNullable`)이나 `Optional` wrapper를 쓴다. -- **B3 — mapper 안의 실패.** record 정규 생성자의 `IllegalArgumentException`, MapStruct가 생성한 NPE, ACL - 정규화 실패 등은 `MappingException`을 던져 대응시킨다. 전역 handler가 그것을 `MAPPING_FAILED`(HTTP 400)로 - 보내고, `BAD_PARAMETER`나 `INTERNAL_ERROR`로 보내지 않는다. mapper가 아닌 호출자의 평범한 - `IllegalArgumentException`은 계속 `BAD_PARAMETER`다. -- **B4 — 검증 층.** 클래스 수준 Bean Validation 제약은 *문법* 층(요청 DTO)에 속한다. 도메인 불변식은 - `application-core` / `domain-core`에 속한다. 문법이 실패하면 `@GroupSequence(...)`로 불변식 평가를 건너뛴다. - `@Valid` cascade 깊이는 3 이하로 둔다. -- **B5 — 다형 역직렬화.** `ObjectMapper.enableDefaultTyping()` / `activateDefaultTyping()`을 부르거나 - `LaissezFaireSubTypeValidator`를 참조하는 것은 CVE-2019-14379 RCE의 입구이고 ArchUnit이 막는다 - (`NO_JACKSON_LAISSEZ_FAIRE_SUBTYPE_VALIDATOR`, `NO_JACKSON_ENABLE_DEFAULT_TYPING_CALL`). sealed `Command` - 타입은 `@JsonTypeInfo(use = NAME)` + `@JsonSubTypes`나 `BasicPolymorphicTypeValidator` 허용 목록을 쓴다. -- **B6 — virtual thread 문맥 전파.** `spring.threads.virtual.enabled=true`이면 `InheritableThreadLocal`을 쓰지 - 않는다(ArchUnit 규칙 `NO_INHERITABLE_THREAD_LOCAL`). filter와 interceptor는 SLF4J 2.0+ MDC나 - `RequestContextHolder`로 `requestId` / `traceId`를 전파한다. -- **B7 — outbound ACL mapper 범위.** outbound HTTP·메시징 어댑터의 응답은 `application-core`나 `domain-core`에 - 닿기 전에 ACL mapper(정규화, 가리기, 공개 필드 고르기)를 거친다 — inbound와 같은 경계 계약이다. 외부 응답 - 원본 타입은 `domain-core`로 새면 안 된다. -- **B8 — bulk endpoint의 부분 성공.** envelope `success = true`는 모든 항목이 성공했을 때뿐이다. 일부가 - 실패하면 `success = false` + `error.code = BATCH_PARTIAL_FAILURE` + `error.details[]`(항목별 배열)로 - 답한다 — 단일 항목 endpoint와 모양이 다르다. 모양이 다르다는 것을 OpenAPI spec에 적는다. - -이 모듈을 쓰는 모듈의 도메인 `@RestControllerAdvice`에는 `@Order(Ordered.HIGHEST_PRECEDENCE)`를 단다(또는 -다른 방법으로 이 모듈의 기본 `GlobalExceptionHandler`보다 앞에 둔다). 그렇지 않으면 기본 handler의 -catch-all `@ExceptionHandler(Exception.class)`가 도메인 예외를 `INTERNAL_ERROR`로 만든다. - -기본 운영 handler(`error/GlobalExceptionHandler`), 오류 코드 계약 -(`dev.caskeleton.shared.error.ApiErrorCode` + `OperationalError`), `error/ErrorResponseFactory`, -`envelope/EnvelopeBodyAdvice`는 이제 운영 모듈(`adapter:inbound:web` / `shared-contract`)에 있어서, 돌아가는 -애플리케이션이 그것을 준다. 기능 전용 예외 handler와 오류 코드는 그 기능을 가진 모듈에 둔다(`docs/manual/06-errors.md`). - -## schema·직렬화 계약 - -`feature-schema-serialization-contract`(설계 기록)가 wire 계약의 *응답을 만드는* 쪽을 정한다 — 위 B1 -*요청을 받는* 정책의 짝이다. 역직렬화 스위치(B1)와 null·빈 값·없음 세 상태(`Patch` + `JsonNullable`, -B2)가 이미 inbound 쪽을 덮고, 아래 규칙이 outbound 쪽을 덮는다. Jackson 속성은 `app-bootstrap`의 -`application.yml`(`spring.jackson.deserialization.*`, `spring.jackson.datatype.*`)에 있다. ArchUnit과 실제 -설정 시험도 `app-bootstrap`에 있다(`JacksonSerializationPolicyTest`, `NO_BIGDECIMAL_DOUBLE_CONSTRUCTOR`). - -- **S1 — 날짜·시간·시간대.** `WRITE_DATES_AS_TIMESTAMPS=false`로 고정하므로 `java.time` 값은 - `JavaTimeModule`을 거쳐 ISO-8601 문자열로 직렬화한다(`OffsetDateTime` → `"...Z"`, `LocalDate` → - `"YYYY-MM-DD"`). 숫자 epoch나 `[y,m,d,...]` 배열이 되지 않는다. 서버 시간대는 **UTC**다: 시각은 `Z` - offset을 가진 `OffsetDateTime`/`Instant`로 낸다. 날짜만 있는 달력 필드에만 `LocalDate`를 쓴다. 시간대 - 없는 `LocalDateTime`을 응답 DTO에 넣지 **않는다** — offset 없이 직렬화되어 계약을 깬다. -- **S2 — 돈·BigDecimal.** 도메인이 따로 적지 않으면 기본 scale 2, 반올림 `HALF_UP`이다(KRW/JPY는 scale 0과 - schema 메모). 값은 지수 표기로 직렬화되지 않는다 — 설정 키로 고정하지 않고 `JacksonSerializationPolicyTest`가 - 큰 값과 끝자리 0을 단언한다. API마다 JSON 표현을 **하나** 고르고 OpenAPI schema에 적는다: 공개·금융 - endpoint는 **string**(`@JsonSerialize(using = ToStringSerializer.class)`. 클라이언트가 파싱하고 정밀도를 - 잃지 않는다), 내부 서비스 사이 endpoint는 **number + plain**. 기본값에 기대지 않는다 — endpoint를 설계할 - 때 정한다. -- **S3 — `new BigDecimal(double)`은 금지다.** `double`/`float` 생성자는 이진 부동소수점 오차를 담는다 - (`new BigDecimal(0.1)` ≠ `0.1`). `String`(`new BigDecimal("0.1")`)이나 `BigDecimal.valueOf(double)`로 - 만든다. ArchUnit 규칙 `NO_BIGDECIMAL_DOUBLE_CONSTRUCTOR`가 강제한다. -- **S4 — enum과 null·빈 값·없음.** 요청 쪽의 모르는 enum → `VALIDATION_FAILED`(B1 - `read-unknown-enum-values-as-null=false`). 옛 값은 명시한 어댑터로 대응시키고 소리 없는 대체값을 쓰지 - 않는다. 없음·명시한 null·값의 구별은 inbound web mapper(Controller DTO → Command)가 가지고 `Patch`(B2)로 - 나타낸다. `domain-core`와 `application-core`는 이미 풀린 세 상태를 받고 wire 타입은 받지 않는다. -- **S5 — 이 브랜치의 범위 밖.** OpenAPI drift 강제는 검증 suite / api-contract-baseline의 몫이다. 지운 - 필드 재사용 금지 도구(`x-removed-fields` 대 markdown catalog)는 `needs-confirmation`이다. outbox·event용 - Avro Schema Registry와 응답 필드 이름 바꾸기·versioning(`feature-api-compatibility-deprecation-contract`)은 - 다른 브랜치다. - -## 업무 규칙 검증 계약 - -`feature-business-rule-validation-contract`(설계 기록)는 **어떤 규칙을 어느 경계에서 검증하는지** 정해서, -「검증」이 controller DTO나 DB 제약 하나로 뭉개지지 않게 한다. 위 경계·대응 계약 위에 놓이고, ArchUnit과 -계약 시험이 강제한다(새 런타임 장치가 아니다). - -| 층 | 소유 | 검증하는 것 | `error.category` | 강제하는 곳 | -|---|---|---|---|---| -| 문법·모양 | `adapter:inbound:web` 요청 DTO(`@Valid` / `jakarta.validation`) | 요청 모양, 타입, 필수 필드 | `VALIDATION` | ArchUnit 규칙 `VALIDATION_CONSTRAINTS_STAY_AT_WEB_BOUNDARY` | -| 유스케이스 정책 | `application-core` | 인가, aggregate를 가로지르는 정책, 상태 전제 조건 | `AUTHZ` / `CONFLICT` | `BusinessRuleValidationContractTest` | -| 도메인 불변식 | `domain-core` 모델·값 객체 **생성자** | 업무 불변식(예: end ≥ start) | `CONFLICT` / `VALIDATION` | 도메인 단위 시험(예: `PeriodTest`) — 생성자가 유일하고 바뀌지 않는 생성 경로다 | -| 영속 무결성 | `adapter:outbound:persistence-jpa`(번역기는 `feature-persistence-failure-baseline`의 것) | unique / FK / check / serialization | `DATA_INTEGRITY` / `CONFLICT` | `BusinessRuleValidationContractTest` + 누출 시험 | - -- **C1 — 검증 애너테이션은 web 경계에 머문다.** `jakarta.validation`(`@NotNull`, `@Valid`, …)은 - `adapter:inbound:web`에만 나와야 한다. `domain-core`와 `application-core`는 불변식과 정책을 평범한 Java로 - 나타낸다. Bean Validation 애너테이션이 `..domain..`이나 `..application..`으로 새면 ArchUnit 규칙 - `VALIDATION_CONSTRAINTS_STAY_AT_WEB_BOUNDARY`가 빌드를 실패시킨다. -- **C2 — 업무 불변식은 도메인에 있고 우회할 수 없다.** 불변식은 값 객체·엔티티 **생성자**(유일한 생성 - 경로)에서 강제하고 타입을 불변으로 둔다. 그래서 어떤 application service나 영속 경로도 불변식을 어긴 - 인스턴스를 내줄 수 없다. DB 제약은 뒷받침일 뿐 유일한 검사가 아니다(금지: 「불변식을 DB 제약으로만 - 지키기」). -- **C3 / C7 — 영속 무결성은 새는 것 없이 운영 오류로 대응한다.** unique·FK·check·serialization 실패는 - **클라이언트에게 안전한 메시지만** 가진 `DATA_INTEGRITY` / `CONFLICT`로 대응한다. SQL 원문, 제약·index - 이름, SQLState 코드, 예외 클래스, stack frame은 `error.message`나 `error.details`에 닿으면 안 된다. 기본 - `GlobalExceptionHandler` catch-all이 이미 메시지를 불투명한 공용 메시지(`ClientErrorMessages.OPAQUE`)로 - 바꾸고 details를 `null`로 낸다. category가 맞는 대응(23505 → `CONFLICT/DB_UNIQUE_VIOLATION`, …)은 - `feature-persistence-failure-baseline`의 영속 어댑터 번역기가 가진다. -- **C8 — 중복 검증에는 정본 소유자가 있어야 한다.** UX나 성능을 위해 같은 규칙을 다른 층에서 미리 검사할 수 - 있다(예: DB unique 제약을 따라 하는 application 사전 검사). 단 그 규칙의 **정본 소유자**를 코드 주석이나 - 관련 `CLAUDE.md`에 적어야 한다. 소유자를 적지 않은 중복 검증기는 리뷰에서 실패다(소리 없이 서로 어긋날 - 위험). 자동 규칙이 아니라 절차 게이트(PR 리뷰)다 — 소유자 표지 애너테이션이 정당해질 때까지 - `needs-confirmation`이다. - -이 브랜치의 범위 밖(참조만 하고 여기서 다시 구현하지 않는다): SQLState → 코드 9행 표와 -`DataAccessException` 번역기(`feature-persistence-failure-baseline`), Jackson B1/B2 요청 경계 스위치와 mapper -표지 예외(`feature-boundary-validation-mapping-contract`), envelope, `Category` enum, `OperationalError` 코드 -(`feature-operational-error-observability-foundation`). - -## 테스트 - -```bash -cd src -./gradlew :adapter:inbound:web:test --console=plain -``` +@AGENTS.md diff --git a/src/adapter/inbound/web/README.md b/src/adapter/inbound/web/README.md index 840517b1..9173bad1 100644 --- a/src/adapter/inbound/web/README.md +++ b/src/adapter/inbound/web/README.md @@ -9,7 +9,7 @@ route inventory)는 opt-in leaf `adapter:inbound:web-advanced` 에 있다 ([README](../web-advanced/README.md)). 허용/금지 의존, 경계 계약(B1~B8), 스키마/직렬화 계약(S1~S5), 비즈니스 규칙 검증 계약(C1~C8), -테스트 명령 같은 **모듈 규칙**은 [CLAUDE.md](CLAUDE.md) 가 SSOT 다. 이 문서는 코드 주석에서 +테스트 명령 같은 **모듈 규칙**은 [AGENTS.md](AGENTS.md) 가 SSOT 다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를 모아둔 참조용 기록이다 — 코드를 읽다 "왜 이렇게 했나"가 궁금할 때 본다. 아래 설명은 별도 추적 ID를 몰라도 읽히도록 결정의 배경과 트레이드오프를 문장으로 풀어 둔다. @@ -197,7 +197,7 @@ commit-aware response wrapper 계약을 구현한다. 또한 이 모듈은 HTML - **D5: RFC 7807 `ProblemDetail` 표현은 거부**하고 자체 `Envelope` 형식을 쓴다. - **운영/전송/보안 예외만** 처리한다. 도메인 예외는 소비 모듈의 별도 `@RestControllerAdvice` 가 처리하고 - Spring 이 두 advice 를 합성(compose)한다(CLAUDE.md 의 `@Order(HIGHEST_PRECEDENCE)` 규칙 참조). + Spring 이 두 advice 를 합성(compose)한다(AGENTS.md 의 `@Order(HIGHEST_PRECEDENCE)` 규칙 참조). - **클라이언트 메시지는 allowlist다.** 예외 메시지, validation interpolated message, rejected request value, raw request URL은 `error.message`/`details`에 넣지 않는다. `error.message`는 항상 shared-contract diff --git a/src/adapter/inbound/websocket/AGENTS.md b/src/adapter/inbound/websocket/AGENTS.md new file mode 100644 index 00000000..cc19b9f8 --- /dev/null +++ b/src/adapter/inbound/websocket/AGENTS.md @@ -0,0 +1,120 @@ +# adapter:inbound:websocket — 고를 때만 켜는 WebSocket·STOMP 경계 + +## 등록 정보 + +- 모듈 ID: `adapter-inbound-websocket` +- Gradle 경로: `:adapter:inbound:websocket` +- 이 모듈만 시험: `./gradlew :adapter:inbound:websocket:test --console=plain` +- 실행 기준: Java 21. Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. +- registry 정본: `src/config/architecture/modules.json` + +패키지 루트: `dev.caskeleton.adapter.inbound.websocket`. + +## 책임 + +이 leaf에는 **서로 다른 범위 둘**이 있고, 배포되는 기능 하나로 읽으면 안 된다. + +1. **골라 쓰는 STOMP·SockJS 채널** — `stomp/**`가 Spring 전송 설정, 타입 있는 `app.websocket.*` 설정, + handshake principal·origin 검사, destination 정책, 정해진 클라이언트 안전 STOMP `ERROR` 대응, 할 수 있는 + 만큼만 하는(best-effort) 프로세스 안 이벤트 projection을 가진다. +2. **servlet handler 라이브러리** — `servlet/`, `outbound/`, `budget/`과 id record 둘 + `core/WebSocketConnectionId`, `protocol/WebSocketMessageId`. 설정 키도 Spring 설정도 없다: 서비스 자신의 + 어댑터 leaf가 `PlatformWebSocketHandler`를 만들고 등록한다. README 「라이브러리 API」가 진입점과 배선을 + 적는다. + +이 leaf는 command 중복을 걸러 내지 않고 저장소 SPI를 가지지 않는다. 예전 `idempotency/` 패키지(command +원장, `WebSocketActorReference`, `WebSocketEndpointName`)는 2026-09-25에 지웠다. 많아야 한 번 돌아야 하는 +command는 그 유스케이스 안에서 애플리케이션 `IdempotencyExecutor`를 거친다. 범위(scope)는 다시 연결해도 +살아남는 값(endpoint + actor + 클라이언트 자신의 message id)이고, connection id가 아니다. + +이 모듈은 출하하는 런타임 조립 둘 어디에도 없다. 등록되고 시험된다고 두 범위 중 어느 것도 켜지지 않는다. + +## 허용 + +- `@DomainEvent` 표지를 위한 `:domain-core` 등록 의존. +- 저장소 BOM이 관리하는 Spring Boot WebSocket·validation starter. +- 시험에서만: 내장 Tomcat·Jetty·SockJS·STOMP 클라이언트와 Testcontainers(Nginx lane). + +## 금지 + +- 어떤 `adapter:outbound:*` 모듈에든 직접 의존하기. +- repository, Spring Data, 영속 엔티티, 업무 정책 접근. +- `@DomainEvent` payload를 그대로 보내기, 리플렉션 기반 이벤트 직렬화. +- 켜져 있을 때 wildcard·빈 handshake origin. +- 익명 handshake, 아무 topic 구독, 클라이언트가 broker destination으로 보내기. +- 이 골격 leaf 안의 운영 기능 `@MessageMapping`. +- 모듈 안의 YAML 파일. 속성 값은 조립 루트가 가진다. +- 이 leaf의 어떤 코드도 하지 않는 동작을 위한 설정 키·flag·catalog. handler가 강제하지 않는 한계는 + `WebSocketConnectionBudget`의 필드가 아니다. +- reactive(WebFlux) WebSocket 코드: 템플릿은 servlet만 쓴다. + +## 타입 있는 설정 (`app.websocket.*`) + +속성 트리 하나와 운영자 env 접두어 하나가 있다: `app.websocket.*` ↔ `APP_WEBSOCKET_*`. STOMP 채널만 +설정한다. 기본 bootJar에는 이 leaf가 없으니, 이 값은 이 leaf를 채택한 조립에서만 뜻이 있다. + +| 속성 | env | 기본값·역할 | +| --- | --- | --- | +| `app.websocket.enabled` | `APP_WEBSOCKET_ENABLED` | `true`. `false`이면 STOMP·SockJS 채널을 끈다 | +| `app.websocket.endpoint` | `APP_WEBSOCKET_ENDPOINT` | `/ws` | +| `app.websocket.allowed-origins` | `APP_WEBSOCKET_ALLOWED_ORIGINS` | `http://localhost:3000`. 명시한 origin만 | +| `app.websocket.broadcast-destination` | `APP_WEBSOCKET_BROADCAST_DESTINATION` | `/topic/events` | +| `app.websocket.channel-queue-capacity` | `APP_WEBSOCKET_CHANNEL_QUEUE_CAPACITY` | `10000`. STOMP 채널마다(클라이언트 inbound, 클라이언트 outbound, broker) 거절하기 전에 쌓아 두는 메시지 수 | +| `app.websocket.message-size-limit` | `APP_WEBSOCKET_MESSAGE_SIZE_LIMIT` | `64KB`(Spring 기본값을 이제 명시한다) | +| `app.websocket.send-buffer-size-limit` | `APP_WEBSOCKET_SEND_BUFFER_SIZE_LIMIT` | `512KB`(Spring 기본값을 이제 명시한다) | +| `app.websocket.send-time-limit` | `APP_WEBSOCKET_SEND_TIME_LIMIT` | `10s`(Spring 기본값을 이제 명시한다) | +| `app.websocket.time-to-first-message` | `APP_WEBSOCKET_TIME_TO_FIRST_MESSAGE` | `60s`(Spring 기본값을 이제 명시한다) | +| `app.websocket.max-connections` | `APP_WEBSOCKET_MAX_CONNECTIONS` | `1000`. 노드마다 STOMP 세션 수. 그다음 것은 1013으로 닫는다 | + +`WebSocketSettings`는 `@Validated`다. 켜진 상태의 잘못된 설정은 context 기동을 실패시킨다. + +## 이 capability 채택하기 + +WebSocket은 기본 bootJar 안에 잠든 기능이 아니라 **빌드 조립에서 고르는 것**이다. + +1. 쓰는 조립의 의존성에 `:adapter:inbound:websocket`을 더하고 `config/architecture/modules.json`에 맞는 허용 + edge를 더한다. +2. 설정 등록은 capability 루트에 둔다. 출하하는 `@ConfigurationPropertiesScan`에 + `dev.caskeleton.adapter.inbound.websocket`을 다시 더하지 않는다. +3. STOMP·SockJS 채널은 이 leaf 자신의 `AutoConfiguration.imports`가 등록하고, leaf가 servlet classpath에 + 있으면 언제나 켜진다. wildcard가 아닌 origin 허용 목록을 정하고, 끄려면 `app.websocket.enabled=false`로 + 한다. +4. handler 라이브러리는 README 「라이브러리 API」를 따른다. handler는 bean이어야 한다. 그래야 그 + `SmartLifecycle` 멈춤(열린 모든 연결에 1001)이 web 서버가 멈추기 전에 돈다. +5. 조립을 승격하기 전에 leaf lane과 저장소 conditional-transport 묶음을 돌린다: + `./gradlew :adapter:inbound:websocket:test :adapter:inbound:websocket:systemTest :conditionalTransportQualification`. + +## inbound 정책 (STOMP) + +- HTTP upgrade에는 이미 비어 있지 않은 `Principal`이 있어야 한다. 어댑터는 credential을 직접 인증하지 않는다. +- STOMP `SUBSCRIBE`는 설정한 broadcast destination에만 허용한다. +- 인증된 `SEND`는 `/app/**` 아래에만 허용한다. +- 클라이언트가 `/topic/**`나 다른 destination으로 보내는 `SEND`는 거절한다. +- 클라이언트에게 보이는 처리 실패는 모두 빈 payload와 정해진 `message` `WEBSOCKET_REQUEST_REJECTED`를 가진 + ERROR frame이 된다. 그 `error-code` header는 cause chain에서 처음 나오는 `ApiErrorCarrier`가 실은 + `ApiErrorCode`(`IllegalArgumentException` 뒤에 있어도), `IllegalArgumentException`이면 `BAD_PARAMETER`, 그 + 밖에는 `WEBSOCKET_REQUEST_REJECTED`다. + +## 이벤트 projection 계약 + +나중의 기능이 정확히 하나의 `@DomainEvent` 클래스에 대해 `LiveEventProjector` bean을 기여할 수 있다. +broadcaster는 projector가 정확히 하나 맞을 때만 보낸다. projector가 없거나 둘 이상이거나, projection이 +실패하거나, 이벤트 타입이 잘못됐거나, 필드가 null이거나, map이 한계를 넘으면 버린다. wire envelope에는 +`type`, 한계 있는 문자열 `fields`, `occurredAt`만 있다. broker 채널은 자기 한계 있는 executor를 가지므로, +simple broker가 구독자에게 퍼뜨리는 일은 도메인 이벤트를 발행한 스레드에서 돌지 않는다. broker queue가 차면 +이벤트를 버린다(best-effort, R1). + +템플릿에는 WebSocket 이벤트를 발행하거나 projector를 기여하는 기능이 없다. + +## 증거와 한계 + +| lane | 증명하는 것 | +| --- | --- | +| `test` | STOMP 설정·정책, queue·writer·budget, handler 크기와 넘침 종료 | +| `systemTest` | 실제 Tomcat: STOMP 경계(`WebSocketBoundaryQualificationTest`), handler 런타임과 남용 계약, context를 닫으면 1001을 보냄 | +| `websocketJettyTest` | Jetty에서 handler 런타임 계약 | +| `websocketNginxTest` | 실제 Nginx 뒤의 upgrade·forwarding(Docker 필요. 없으면 실패한다) | +| `websocketTransportQualificationTest` | STOMP 경계 시험을 건너뛰지 않고 실행 | + +simple broker는 로컬·단일 프로세스·best-effort R1 증거일 뿐이다. broker relay, 여러 노드·durable 전달, +롤백에 안전한 발행, replay·resume은 주지 않는다. diff --git a/src/adapter/inbound/websocket/CLAUDE.md b/src/adapter/inbound/websocket/CLAUDE.md index cc19b9f8..43c994c2 100644 --- a/src/adapter/inbound/websocket/CLAUDE.md +++ b/src/adapter/inbound/websocket/CLAUDE.md @@ -1,120 +1 @@ -# adapter:inbound:websocket — 고를 때만 켜는 WebSocket·STOMP 경계 - -## 등록 정보 - -- 모듈 ID: `adapter-inbound-websocket` -- Gradle 경로: `:adapter:inbound:websocket` -- 이 모듈만 시험: `./gradlew :adapter:inbound:websocket:test --console=plain` -- 실행 기준: Java 21. Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. -- registry 정본: `src/config/architecture/modules.json` - -패키지 루트: `dev.caskeleton.adapter.inbound.websocket`. - -## 책임 - -이 leaf에는 **서로 다른 범위 둘**이 있고, 배포되는 기능 하나로 읽으면 안 된다. - -1. **골라 쓰는 STOMP·SockJS 채널** — `stomp/**`가 Spring 전송 설정, 타입 있는 `app.websocket.*` 설정, - handshake principal·origin 검사, destination 정책, 정해진 클라이언트 안전 STOMP `ERROR` 대응, 할 수 있는 - 만큼만 하는(best-effort) 프로세스 안 이벤트 projection을 가진다. -2. **servlet handler 라이브러리** — `servlet/`, `outbound/`, `budget/`과 id record 둘 - `core/WebSocketConnectionId`, `protocol/WebSocketMessageId`. 설정 키도 Spring 설정도 없다: 서비스 자신의 - 어댑터 leaf가 `PlatformWebSocketHandler`를 만들고 등록한다. README 「라이브러리 API」가 진입점과 배선을 - 적는다. - -이 leaf는 command 중복을 걸러 내지 않고 저장소 SPI를 가지지 않는다. 예전 `idempotency/` 패키지(command -원장, `WebSocketActorReference`, `WebSocketEndpointName`)는 2026-09-25에 지웠다. 많아야 한 번 돌아야 하는 -command는 그 유스케이스 안에서 애플리케이션 `IdempotencyExecutor`를 거친다. 범위(scope)는 다시 연결해도 -살아남는 값(endpoint + actor + 클라이언트 자신의 message id)이고, connection id가 아니다. - -이 모듈은 출하하는 런타임 조립 둘 어디에도 없다. 등록되고 시험된다고 두 범위 중 어느 것도 켜지지 않는다. - -## 허용 - -- `@DomainEvent` 표지를 위한 `:domain-core` 등록 의존. -- 저장소 BOM이 관리하는 Spring Boot WebSocket·validation starter. -- 시험에서만: 내장 Tomcat·Jetty·SockJS·STOMP 클라이언트와 Testcontainers(Nginx lane). - -## 금지 - -- 어떤 `adapter:outbound:*` 모듈에든 직접 의존하기. -- repository, Spring Data, 영속 엔티티, 업무 정책 접근. -- `@DomainEvent` payload를 그대로 보내기, 리플렉션 기반 이벤트 직렬화. -- 켜져 있을 때 wildcard·빈 handshake origin. -- 익명 handshake, 아무 topic 구독, 클라이언트가 broker destination으로 보내기. -- 이 골격 leaf 안의 운영 기능 `@MessageMapping`. -- 모듈 안의 YAML 파일. 속성 값은 조립 루트가 가진다. -- 이 leaf의 어떤 코드도 하지 않는 동작을 위한 설정 키·flag·catalog. handler가 강제하지 않는 한계는 - `WebSocketConnectionBudget`의 필드가 아니다. -- reactive(WebFlux) WebSocket 코드: 템플릿은 servlet만 쓴다. - -## 타입 있는 설정 (`app.websocket.*`) - -속성 트리 하나와 운영자 env 접두어 하나가 있다: `app.websocket.*` ↔ `APP_WEBSOCKET_*`. STOMP 채널만 -설정한다. 기본 bootJar에는 이 leaf가 없으니, 이 값은 이 leaf를 채택한 조립에서만 뜻이 있다. - -| 속성 | env | 기본값·역할 | -| --- | --- | --- | -| `app.websocket.enabled` | `APP_WEBSOCKET_ENABLED` | `true`. `false`이면 STOMP·SockJS 채널을 끈다 | -| `app.websocket.endpoint` | `APP_WEBSOCKET_ENDPOINT` | `/ws` | -| `app.websocket.allowed-origins` | `APP_WEBSOCKET_ALLOWED_ORIGINS` | `http://localhost:3000`. 명시한 origin만 | -| `app.websocket.broadcast-destination` | `APP_WEBSOCKET_BROADCAST_DESTINATION` | `/topic/events` | -| `app.websocket.channel-queue-capacity` | `APP_WEBSOCKET_CHANNEL_QUEUE_CAPACITY` | `10000`. STOMP 채널마다(클라이언트 inbound, 클라이언트 outbound, broker) 거절하기 전에 쌓아 두는 메시지 수 | -| `app.websocket.message-size-limit` | `APP_WEBSOCKET_MESSAGE_SIZE_LIMIT` | `64KB`(Spring 기본값을 이제 명시한다) | -| `app.websocket.send-buffer-size-limit` | `APP_WEBSOCKET_SEND_BUFFER_SIZE_LIMIT` | `512KB`(Spring 기본값을 이제 명시한다) | -| `app.websocket.send-time-limit` | `APP_WEBSOCKET_SEND_TIME_LIMIT` | `10s`(Spring 기본값을 이제 명시한다) | -| `app.websocket.time-to-first-message` | `APP_WEBSOCKET_TIME_TO_FIRST_MESSAGE` | `60s`(Spring 기본값을 이제 명시한다) | -| `app.websocket.max-connections` | `APP_WEBSOCKET_MAX_CONNECTIONS` | `1000`. 노드마다 STOMP 세션 수. 그다음 것은 1013으로 닫는다 | - -`WebSocketSettings`는 `@Validated`다. 켜진 상태의 잘못된 설정은 context 기동을 실패시킨다. - -## 이 capability 채택하기 - -WebSocket은 기본 bootJar 안에 잠든 기능이 아니라 **빌드 조립에서 고르는 것**이다. - -1. 쓰는 조립의 의존성에 `:adapter:inbound:websocket`을 더하고 `config/architecture/modules.json`에 맞는 허용 - edge를 더한다. -2. 설정 등록은 capability 루트에 둔다. 출하하는 `@ConfigurationPropertiesScan`에 - `dev.caskeleton.adapter.inbound.websocket`을 다시 더하지 않는다. -3. STOMP·SockJS 채널은 이 leaf 자신의 `AutoConfiguration.imports`가 등록하고, leaf가 servlet classpath에 - 있으면 언제나 켜진다. wildcard가 아닌 origin 허용 목록을 정하고, 끄려면 `app.websocket.enabled=false`로 - 한다. -4. handler 라이브러리는 README 「라이브러리 API」를 따른다. handler는 bean이어야 한다. 그래야 그 - `SmartLifecycle` 멈춤(열린 모든 연결에 1001)이 web 서버가 멈추기 전에 돈다. -5. 조립을 승격하기 전에 leaf lane과 저장소 conditional-transport 묶음을 돌린다: - `./gradlew :adapter:inbound:websocket:test :adapter:inbound:websocket:systemTest :conditionalTransportQualification`. - -## inbound 정책 (STOMP) - -- HTTP upgrade에는 이미 비어 있지 않은 `Principal`이 있어야 한다. 어댑터는 credential을 직접 인증하지 않는다. -- STOMP `SUBSCRIBE`는 설정한 broadcast destination에만 허용한다. -- 인증된 `SEND`는 `/app/**` 아래에만 허용한다. -- 클라이언트가 `/topic/**`나 다른 destination으로 보내는 `SEND`는 거절한다. -- 클라이언트에게 보이는 처리 실패는 모두 빈 payload와 정해진 `message` `WEBSOCKET_REQUEST_REJECTED`를 가진 - ERROR frame이 된다. 그 `error-code` header는 cause chain에서 처음 나오는 `ApiErrorCarrier`가 실은 - `ApiErrorCode`(`IllegalArgumentException` 뒤에 있어도), `IllegalArgumentException`이면 `BAD_PARAMETER`, 그 - 밖에는 `WEBSOCKET_REQUEST_REJECTED`다. - -## 이벤트 projection 계약 - -나중의 기능이 정확히 하나의 `@DomainEvent` 클래스에 대해 `LiveEventProjector` bean을 기여할 수 있다. -broadcaster는 projector가 정확히 하나 맞을 때만 보낸다. projector가 없거나 둘 이상이거나, projection이 -실패하거나, 이벤트 타입이 잘못됐거나, 필드가 null이거나, map이 한계를 넘으면 버린다. wire envelope에는 -`type`, 한계 있는 문자열 `fields`, `occurredAt`만 있다. broker 채널은 자기 한계 있는 executor를 가지므로, -simple broker가 구독자에게 퍼뜨리는 일은 도메인 이벤트를 발행한 스레드에서 돌지 않는다. broker queue가 차면 -이벤트를 버린다(best-effort, R1). - -템플릿에는 WebSocket 이벤트를 발행하거나 projector를 기여하는 기능이 없다. - -## 증거와 한계 - -| lane | 증명하는 것 | -| --- | --- | -| `test` | STOMP 설정·정책, queue·writer·budget, handler 크기와 넘침 종료 | -| `systemTest` | 실제 Tomcat: STOMP 경계(`WebSocketBoundaryQualificationTest`), handler 런타임과 남용 계약, context를 닫으면 1001을 보냄 | -| `websocketJettyTest` | Jetty에서 handler 런타임 계약 | -| `websocketNginxTest` | 실제 Nginx 뒤의 upgrade·forwarding(Docker 필요. 없으면 실패한다) | -| `websocketTransportQualificationTest` | STOMP 경계 시험을 건너뛰지 않고 실행 | - -simple broker는 로컬·단일 프로세스·best-effort R1 증거일 뿐이다. broker relay, 여러 노드·durable 전달, -롤백에 안전한 발행, replay·resume은 주지 않는다. +@AGENTS.md diff --git a/src/adapter/inbound/websocket/README.md b/src/adapter/inbound/websocket/README.md index 8bb1bf11..31c91557 100644 --- a/src/adapter/inbound/websocket/README.md +++ b/src/adapter/inbound/websocket/README.md @@ -1,6 +1,6 @@ # adapter-inbound-websocket -모듈 규칙(허용 의존, 설정 키, 테스트 명령)은 [CLAUDE.md](CLAUDE.md)가 SSOT다. 이 문서는 무엇을 +모듈 규칙(허용 의존, 설정 키, 테스트 명령)은 [AGENTS.md](AGENTS.md)가 SSOT다. 이 문서는 무엇을 제공하는지, 어떻게 붙이는지, 왜 이런 모양인지를 적는다. 이 leaf는 두 가지를 제공한다. 서로 참조하지 않는다. diff --git a/src/adapter/outbound/cache-redis/AGENTS.md b/src/adapter/outbound/cache-redis/AGENTS.md new file mode 100644 index 00000000..b00bee92 --- /dev/null +++ b/src/adapter/outbound/cache-redis/AGENTS.md @@ -0,0 +1,180 @@ +# adapter:outbound:cache-redis — cache와 Redis 어댑터 + +## 등록 정보 + +- 모듈 ID: `adapter-outbound-cache-redis` +- Gradle 경로: `:adapter:outbound:cache-redis` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:cache-redis:test --console=plain` +- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. +- registry 정본: `src/config/architecture/modules.json`. + +패키지 루트: `dev.caskeleton.adapter.outbound.cache`. + +## 책임 + +- `application-core`의 semantic cache 포트를 구현하고, Redis 개념을 core에 드러내지 않는다. +- 정해진 물리 키, digest, codec·envelope, program catalog, 타입 있는 Redis 원자 창구, runtime client 연결, + capability별 실패 뜻을 가진다. +- semantic cache 포트(`CacheRegionPort`) 뒤에서 절대 soft·hard 만료, 쓰기 조건, 키 무효화 표지를 구현한다. TTL + jitter도 stampede 보호도 없다. single-flight는 호출자의 몫이다. revision 순서는 포트의 + `CacheSourceRevisionOrder`다. Lua 사본은 `CacheRegionContract`(application-core testFixtures)가 그 순서에 + 맞추고, `RedisCacheRegionContractTest`와 `LiveRedisCacheRegionContractTest`가 그 계약을 상속한다. +- provider 중립 `EdgeRateLimitPort`를 전용 조율 Redis 설정, 연결·admission, 전용 키, 버전 있는 원자 program으로 + 구현한다. +- 쓰는 쪽이 semantic 포트로 옮기는 동안 옛 cache router를 떼어 둔다. +- 공용 outbound 관심사는 `adapter:outbound:support`를 다시 쓴다. +- semantic 어댑터가 쓰는 공용 topology client, 연결 lifecycle, `SemanticRedisCommands` 여덟 개, 조건부 Redis + runtime 조립은 `:adapter:outbound:redis-runtime`에 의존한다. +- 범용 typed SDK는 따로 둔 라이브러리 leaf `:adapter:outbound:redis-sdk`에 둔다(그 `README.md`를 본다). 이 + leaf는 시험을 포함해 어떤 설정에서도 그것에 의존하지 않는다. SDK의 시험과 lane은 그 leaf에 있다. + +## Redis 런타임과 골라 쓰는 typed SDK (`…cache.redis.runtime`, `…cache.redis.sdk`) + +등록된 leaf 둘, 패키지 둘, 방향 하나: SDK는 runtime 위에 서고, runtime은 SDK를 모른다(runtime 안의 +`RedisRuntimePackageBoundaryTest`가 그 방향을 지킨다). + +- `:adapter:outbound:redis-runtime`은 운영 기반이다: `RedisRuntimeSettings` 바인딩, credential 해석, topology + client, runtime 자신의 lane(`RedisConnectionKind.REGULAR`, `SCRIPT`)을 가진 `RedisRuntimeOwner`, + `SemanticRedisCommands`(이 leaf와 health contributor가 보내는 명령 여덟 개), health. `cache-redis`가 이 leaf에 + 의존한다. +- `:adapter:outbound:redis-sdk`는 골라 쓰는 범용 typed API를 가진다: `RedisCommandGateway`(`SemanticRedisCommands`를 + 상속), 명령 catalog·정책, operation 예산, 명령 guard, raw·admin surface, programmability, extension — 그리고 + 자기 lane(`RedisSdkLane`: blocking, transaction, admin)과 admin 계정. 서비스가 그것을 + `RedisLaneContribution`/`RedisAccountContribution` bean으로 runtime에 기여한다(`RedisSdkComposition`). + `cache-redis`는 운영에서도 시험에서도 그것에 의존하지 **않는다**. +- 이 leaf의 semantic cache·멱등성·rate-limit·lease 어댑터는 runtime의 `SemanticRedisCommands`를 자기의 닫힌 + semantic program(`RegisteredLuaScript`)으로 보낸다. `CommandPolicyGuard`를 지나지 않고, + `redis-command-policy.yml`이 그것을 다루지 않는다. +- 정확성을 위해 어떤 role에 Redis가 필요한지는 이 leaf의 `RedisCorrectnessRoleSelectors`가 정하고, + `META-INF/spring.factories`에 runtime의 `RedisCorrectnessRequirement`로 등록한다. + +`docs/design/2026-08-07-redis-wrapper-typed-api-design.md`가 설명하는 typed SDK는 출하하는 semantic Redis 어댑터의 +일부가 아니라 골라 쓰는 라이브러리로 남는다. 전달 상태와 맞춘 이력은 +`docs/history/plans/2026-08-07-redis-wrapper-typed-api-status.md`에 있다. + +- `sdk.api..`는 공개 계약이다. Spring, Lettuce, Micrometer, SDK 구현 패키지를 import하지 않는다. Reactor는 + `sdk.api.reactive` 안에만 둔다. +- `sdk.lettuce..`가 계약을 구현한다. `sdk.config`는 속성, capability probe, 허가 정본을 가진다. +- `:adapter:outbound:redis-sdk/src/main/resources/redis-sdk/redis-command-policy.yml`이 골라 쓰는 typed SDK의 명령 + 정책 정본이다. 거기 분류되지 않은 typed SDK 명령은 거절한다. 이 leaf의 semantic capability 어댑터를 위한 정책 + 파일이 아니다. +- `sdk.lettuce.operations`가 타입 있는 operation을 구현한다. 거기 있는 모든 것은 Lettuce에 닿는 유일한 이음매인 + `RedisCommandGateway`를 거치고, 모든 호출은 돌기 전에 `CommandPolicyGuard`의 허가를 받는다. operation에서 + driver를 직접 부르지 않는다. +- `sdk.cluster`는 client 쪽 slot 계산과 cluster 관찰을 가진다. `sdk.api`에만 의존하고 Lettuce를 import하지 + 않는다: slot을 명령을 만들기 전에 계산하므로 `CommandPolicyGuard`가 서버 redirect로 알게 되기 전에 cross-slot + 요청을 거절할 수 있다. +- `sdk.programmability`는 트랜잭션, 등록된 Lua script, 배포된 function 호출을 가진다. 호출 때 script 본문을 받지 + 않는다: catalog가 `EVAL`을 막고 `RedisScriptRegistry` digest의 `EVALSHA`만 닿을 수 있다. `FUNCTION LOAD`는 + 애플리케이션이 아니라 admin plane이다. +- 트랜잭션은 `WATCH`/`MULTI`/`EXEC`이고 **절대** 롤백하지 않는다. `TransactionResult`는 「실행됨」이나 「감시한 + 키가 바뀌어서 아무것도 돌지 않음」만 알리고, 이 패키지의 어떤 타입도 다른 뜻을 비치는 말을 주지 않는다. + 줄 세운 명령은 `QueuedReply`를 돌려주고, 커밋 전에 읽으면 던진다. 그 창 안에서 서버는 `+QUEUED`만 답했기 + 때문이다. 줄 세운 명령도 보통 명령과 같은 `CommandPolicyGuard` 허가를 지난다 — 트랜잭션은 guard를 피하는 길이 + 아니다 — 그리고 창은 던진 callback을 포함해 모든 출구에서 닫는다. `MULTI` 상태로 버려진 연결은 다음 호출자의 + 명령을 소리 없이 줄 세우기 때문이다. queue는 일부러 쓰기 전용이다: 창 안의 읽기로는 분기할 수 없으니, + 트랜잭션이 기대는 읽기는 그 앞에서 `WATCH` 아래에 둔다. +- `sdk.raw`는 승인된 raw 명령 gateway다. catalog가 `RAW_ONLY`로 표시했고 *그리고* 배포가 그 명령에 + `ApprovedRawCommand`를 등록했을 때만 닿을 수 있다. 보내기 전에 인자에서 키를 다시 파싱해 namespace를 검사한다. + 명령 이름을 문자열로 받는 메서드를 여기 더하지 않는다. +- `sdk.admin`은 읽기 전용 진단 plane이다. 자기 gateway(admin ACL 계정, 자기 연결)를 받고, catalog가 `ADMIN_ONLY`이자 + 읽기 전용으로 분류하지 않은 명령은 모두 거절하며, slow log나 client 목록이 인자·상대 주소·연결 이름을 싣지 + 않게 응답을 걸러 낸다. +- `sdk.extensions.*`는 Redis 8 모듈(JSON, Search, Time Series, Probabilistic)을 담는다. 모든 bean은 + `ifSupported(...)`로 만든다 — capability probe가 정하고, catalog 최소값은 앞 걸러내기일 뿐이다 — 그리고 모두 + `ExtensionCommandRunner`로 명령을 만들어 guard가 그 키를 본다. Search는 이것을 보여 주는 예외다: index는 키가 + 아니라서 그 이름은 `LettuceRedisSearchOperations`가 직접 namespace를 붙인다. +- `RedisSdkModuleBoundaryTest`(`redis-sdk` 안)가 `redis-sdk` 소스 루트를 scan해 내부 패키지 그래프, driver 가두기, + 아무 문자열 명령 surface 없음, 설계한 모듈 목록을 강제한다. +- 설계를 다시 보지 않고 바꾸면 안 되는 결정: 한계 없는 `entries`, `members`, `rangeAll`, `keys` 없음. 선택 사항인 + R2 허가·예산 없음. 아무 명령 문자열을 받는 overload 없음. timeout 뒤 멱등이 아닌 쓰기의 자동 재시도 없음. + metric이나 trace tag에 실제 키 없음. + +## 경계 + +- 허용 의존 edge는 이 모듈의 `src/config/architecture/modules.json` 항목에서만 온다. +- inbound 전송, 영속 엔티티·repository, bootstrap, 샘플 의존이 없다. +- cache 어댑터는 업무상 신선도, 자격, 도메인 대체 규칙을 정하지 않는다. +- Redis 물리 TTL은 인코딩한 hard 만료와 같아야 한다. 미래·손상 schema가 보통 miss로 뭉개지면 안 된다. +- application·domain 코드는 raw Redis 키, 명령, Lua·Function 이름, SDK 객체, topology, 연결 타입을 받으면 안 된다. +- cache의 fail-open 동작을 session, 멱등성, 엄격한 quota, lease, fencing에 다시 쓰면 안 된다. +- rate-limit 조립은 `app.cache.redis`, 그 연결, 외부 client 모드, 실패하면 열리는 뜻을 다시 쓰면 안 된다. v1은 + 조율 role이고 실패하면 닫히는 것뿐이다. +- standalone runtime·cache 서비스 lane은 R1 증거일 뿐이다. Sentinel·Cluster, TLS·ACL, 영속·재시작, eviction, 장애 + 증거는 R2를 위해 따로 필요하다. + +## 테스트 + +이 모듈만 보는 시험은 semantic 어댑터를 `testFixtures(project(':adapter:outbound:redis-runtime'))`의 +`InMemorySemanticRedisCommands`에 대고 돌린다. `SemanticRedisCommands`의 유일한 fake이고, `StubRedisRuntimeClient`를 +거쳐 쓴다. R1·R2 승격에는 따로 실제 Redis 서비스 lane이 필요하다. 그 lane을 골랐으면 소리 없이 건너뛰면 안 된다. + +실제 서버 lane이 둘 있다. `redisContainerContractTest`(integration category, `integrationCheck`에만 있다 — 이 leaf의 +`mainCheck`에도 있었을 때는 main push마다 두 번 돌았다)는 Testcontainers로 자기 Redis를 띄운다 — +`config/testing/container-images.properties`의 `redis` image이고 `compose/redis/acl/lane-fixture-accounts.acl`을 +읽어 들인다 — 그리고 `LiveRedisCacheRegionContractTest`, `LiveRedisDistributedLeaseContractTest`, +`LiveRedisIdempotencyStoreContractTest`(메모리 fake도 통과하는 `application-core` 포트 계약), +`LiveRedisSemanticPortsTest`, `LiveRedisSemanticScriptAclProbeTest`를 돌린다. 건너뛰기가 있으면 실패한다 +(2026-11-01부터). 멱등성 계약은 2026-11-03까지 명시할 때만 도는 topology lane에만 있었다. 그래서 Lua 상태 기계의 +낡은 handle, 갱신 거절, 재시도 경우가 어느 게이트에서도 실제 서버에 닿지 않았다. `RedisTestContainer`는 그 lane이 +ACL 파일을 이름으로 댈 때만 서버를 띄운다. + +`redisTopologyTest`는 외부 topology lane이고 `ca.redis-topology-lane`으로 선언한다. 이 leaf는 `standalone`과 +`cluster`(`LiveRedisSemanticPortsTest`, `LiveRedisSemanticScriptAclProbeTest`)를 선언한다. `redis-runtime`과 +`redis-sdk`는 자기 클래스에 대해 자기 lane을 선언한다. 고를 때만 돌고 실패하면 닫힌다: 모드는 `standalone`, +`sentinel`, `cluster`, `tls` 중 이 leaf가 선언한 것이어야 하고, endpoint 속성이 있어야 하며(`sentinel`은 +`redis.topology.master`가, `tls`는 `redis.topology.trust-material`이 더 필요하다), 시험을 하나도 찾지 못하거나 +돌리지 않은 실행은 실패하고(그것은 이 leaf가 아니라 규약이 가진다), leaf가 `redisTopologyLane`에 적은 클래스가 +실제로 돌았어야 하며, 건너뛴 시험은 실행한 것으로 세지 않고 실행을 실패시킨다. `tls`는 배포 모드가 아니라 +lane이다 — 모양은 standalone이고 태스크가 그렇게 대응시킨다. 검증하는 것이 전송이기 때문이다. + +예전 검사 둘은 없어졌다. 시험 소스에서 글자 그대로 `@Tag("redis-topology")`를 찾는 scan은 +`failOnNoDiscoveredTests`가 이미 내는 실패의 메시지를 낫게 할 뿐이었고, 같은 글을 담은 주석으로도 만족됐다. 손으로 +관리하던 모드별 실행 수 하한(20/20/24/4)은 경우를 더하거나 뺄 때마다 고쳐야 했고, 그것이 잡는 「덮는 범위가 +줄었다」는 런타임·배포·데이터·보안·컴파일 실패가 아니다. + +## 조립 + +`RedisRuntimeAutoConfiguration`은 이제 `:adapter:outbound:redis-runtime`의 것이다. Redis 설정과 공용 runtime 기반이 +생기는 유일한 곳이고, `app.redis.enabled`(env `APP_REDIS_ENABLED`, 기본 `true` — 모듈이 있으면 켜진다)가 true인 +동안에만 있다. topology client, 연결 owner, health contributor를 만든다. 이 leaf의 `RedisCapabilityConfig`(자기 +`AutoConfiguration.imports`)가 그 runtime 위에 semantic 포트를 조립한다. + +골라 쓰는 `:adapter:outbound:redis-sdk`는 출하하는 애플리케이션이 자동으로 조립하지 않는다. 그 +`RedisStartupProbe`는 라이브러리 API이고 숨은 운영 guard가 아니다. 특히 `APP_REDIS_ACKNOWLEDGED_WRITE_LOSS_ACCEPTED` +스위치는 없다: 그 거래를 받아들이는 것은 운영 호출자가 없는 공개 설정이 아니라 probe를 부르는 곳의 명시한 인자여야 +한다. + +모든 capability는 `CapabilityKeyspace`를 거쳐 `app.redis.namespace`의 namespace 하나 — +`{environment}:{service}:{domain}` — 아래에 키를 만든다. capability에 자기 접두어 token을 주지 않는다: capability 넷이 +각자 자유 문자열 둘을 이어 붙였더니 키 모양이 넷이 됐고, 배포의 ACL pattern은 그중 어느 것과도 맞지 않았다. + +lane은 서로 다른 계정으로 인증한다. `RedisLane.account()`가 lane의 `RedisAccount`를 이름으로 대고, topology factory는 +*설정한* 계정마다 client를 하나 만든다 — 그래서 계정이 하나인 배포는 여전히 client 하나와 event loop 하나만 가진다. +`SCRIPT` lane이 그것이 있는 이유다: `SCRIPT LOAD`와 `EVALSHA`는 advanced 계정의 것이라서, cache 항목을 읽는 계정은 +script를 실행할 수 없다. + +cache의 조건부 쓰기는 같은 계정이지만 자기 lane `CacheScriptLane.CACHE_SCRIPT`에서 돈다 +(`app.capabilities.cache.maximum-script-connections`, `RedisCacheConfig`가 `RedisLaneContribution`으로 기여한다). +`SCRIPT`로 되돌리지 않는다: 그 lane은 멱등성·rate-limit·lease의 예산이고, 부하를 받는 cache가 그것을 가져가면 +안 된다(2026-11-03에 정함). lane마다 기다림, 거절, 재연결은 `redis-runtime`의 meter(`RedisLaneMetrics`, `redis.lane.*`, +tag `lane`)이다. 그래서 cache가 `SCRIPT`를 쓰지 않는지는 짐작이 아니라 조회로 안다. `DEGRADED` health 순서는 +`redis-runtime`과 함께 나가고, 그 leaf가 상태를 알린다(`config/module-defaults/redis-runtime.yml`). + +Cluster 트랜잭션은 노드 하나에서 돈다. 그래서 SDK의 `RedisTransactionRunner`는 감시한 키(또는 명시한 +`RedisSlotTag`)에서 routing 키를 끌어내고, 그 slot을 가진 노드에서 키의 주인에 고정된 `RedisSdkLane.TRANSACTION`을 +빌린다. route된 lease는 pool에 두지 않는다: pool에 둔 연결은 앞 호출자의 노드에 고정되어 있다. + +설정 바인딩은 capability 기준 4(접두어 하나, `StrictSettingsBinder`)의 기록된 예외다(2026-11-03에 정함): +`app.redis.*`는 `redis-runtime`이 setter와 `validate()`로 바인딩한다. 그 leaf는 프로젝트 의존이 없어서 +`StrictSettingsBinder`(support)에 닿을 수 없기 때문이다. `app.capabilities.*`(cache, lease, rate-limit provider)는 이 +leaf가 공용 capability 선택 루트 아래에서 엄격하게 바인딩한다. `app.rate-limit.*`은 이 leaf가 읽기만 하는 HTTP +경계의 스위치다. 키 이름을 바꾸면 동작 이득 없이 모든 배포의 환경이 깨지니 세 트리를 그대로 둔다. 새 Redis 설정은 +그중 하나에 넣고, 네 번째 트리를 만들지 않는다. + +`RedisRuntimeSettings`에는 클래스 수준 `@ConfigurationProperties`를 달면 안 된다: `RedisRuntimeAutoConfiguration`이 +그것을 바인딩하므로 `APP_REDIS_ENABLED=false`이면 Redis 설정을 하나도 바인딩하지 않는다. 이 패키지에 닿는 +properties scan은 그래도 그것을 바인딩하게 된다(bootstrap의 `@ConfigurationPropertiesScan`은 +`dev.caskeleton.bootstrap.*` 패키지만 적는다). role 선택자(cache 바인딩, session 인증 모드, 멱등성·lease·rate-limit +provider)는 어떤 capability를 조립할지 고른다. 그중 어느 것도 Redis를 켜지 않고, 전역 스위치가 꺼져 있으면 이 +모듈은 bean을 하나도 기여하지 않는다. diff --git a/src/adapter/outbound/cache-redis/CLAUDE.md b/src/adapter/outbound/cache-redis/CLAUDE.md index b00bee92..43c994c2 100644 --- a/src/adapter/outbound/cache-redis/CLAUDE.md +++ b/src/adapter/outbound/cache-redis/CLAUDE.md @@ -1,180 +1 @@ -# adapter:outbound:cache-redis — cache와 Redis 어댑터 - -## 등록 정보 - -- 모듈 ID: `adapter-outbound-cache-redis` -- Gradle 경로: `:adapter:outbound:cache-redis` -- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:cache-redis:test --console=plain` -- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. -- registry 정본: `src/config/architecture/modules.json`. - -패키지 루트: `dev.caskeleton.adapter.outbound.cache`. - -## 책임 - -- `application-core`의 semantic cache 포트를 구현하고, Redis 개념을 core에 드러내지 않는다. -- 정해진 물리 키, digest, codec·envelope, program catalog, 타입 있는 Redis 원자 창구, runtime client 연결, - capability별 실패 뜻을 가진다. -- semantic cache 포트(`CacheRegionPort`) 뒤에서 절대 soft·hard 만료, 쓰기 조건, 키 무효화 표지를 구현한다. TTL - jitter도 stampede 보호도 없다. single-flight는 호출자의 몫이다. revision 순서는 포트의 - `CacheSourceRevisionOrder`다. Lua 사본은 `CacheRegionContract`(application-core testFixtures)가 그 순서에 - 맞추고, `RedisCacheRegionContractTest`와 `LiveRedisCacheRegionContractTest`가 그 계약을 상속한다. -- provider 중립 `EdgeRateLimitPort`를 전용 조율 Redis 설정, 연결·admission, 전용 키, 버전 있는 원자 program으로 - 구현한다. -- 쓰는 쪽이 semantic 포트로 옮기는 동안 옛 cache router를 떼어 둔다. -- 공용 outbound 관심사는 `adapter:outbound:support`를 다시 쓴다. -- semantic 어댑터가 쓰는 공용 topology client, 연결 lifecycle, `SemanticRedisCommands` 여덟 개, 조건부 Redis - runtime 조립은 `:adapter:outbound:redis-runtime`에 의존한다. -- 범용 typed SDK는 따로 둔 라이브러리 leaf `:adapter:outbound:redis-sdk`에 둔다(그 `README.md`를 본다). 이 - leaf는 시험을 포함해 어떤 설정에서도 그것에 의존하지 않는다. SDK의 시험과 lane은 그 leaf에 있다. - -## Redis 런타임과 골라 쓰는 typed SDK (`…cache.redis.runtime`, `…cache.redis.sdk`) - -등록된 leaf 둘, 패키지 둘, 방향 하나: SDK는 runtime 위에 서고, runtime은 SDK를 모른다(runtime 안의 -`RedisRuntimePackageBoundaryTest`가 그 방향을 지킨다). - -- `:adapter:outbound:redis-runtime`은 운영 기반이다: `RedisRuntimeSettings` 바인딩, credential 해석, topology - client, runtime 자신의 lane(`RedisConnectionKind.REGULAR`, `SCRIPT`)을 가진 `RedisRuntimeOwner`, - `SemanticRedisCommands`(이 leaf와 health contributor가 보내는 명령 여덟 개), health. `cache-redis`가 이 leaf에 - 의존한다. -- `:adapter:outbound:redis-sdk`는 골라 쓰는 범용 typed API를 가진다: `RedisCommandGateway`(`SemanticRedisCommands`를 - 상속), 명령 catalog·정책, operation 예산, 명령 guard, raw·admin surface, programmability, extension — 그리고 - 자기 lane(`RedisSdkLane`: blocking, transaction, admin)과 admin 계정. 서비스가 그것을 - `RedisLaneContribution`/`RedisAccountContribution` bean으로 runtime에 기여한다(`RedisSdkComposition`). - `cache-redis`는 운영에서도 시험에서도 그것에 의존하지 **않는다**. -- 이 leaf의 semantic cache·멱등성·rate-limit·lease 어댑터는 runtime의 `SemanticRedisCommands`를 자기의 닫힌 - semantic program(`RegisteredLuaScript`)으로 보낸다. `CommandPolicyGuard`를 지나지 않고, - `redis-command-policy.yml`이 그것을 다루지 않는다. -- 정확성을 위해 어떤 role에 Redis가 필요한지는 이 leaf의 `RedisCorrectnessRoleSelectors`가 정하고, - `META-INF/spring.factories`에 runtime의 `RedisCorrectnessRequirement`로 등록한다. - -`docs/design/2026-08-07-redis-wrapper-typed-api-design.md`가 설명하는 typed SDK는 출하하는 semantic Redis 어댑터의 -일부가 아니라 골라 쓰는 라이브러리로 남는다. 전달 상태와 맞춘 이력은 -`docs/history/plans/2026-08-07-redis-wrapper-typed-api-status.md`에 있다. - -- `sdk.api..`는 공개 계약이다. Spring, Lettuce, Micrometer, SDK 구현 패키지를 import하지 않는다. Reactor는 - `sdk.api.reactive` 안에만 둔다. -- `sdk.lettuce..`가 계약을 구현한다. `sdk.config`는 속성, capability probe, 허가 정본을 가진다. -- `:adapter:outbound:redis-sdk/src/main/resources/redis-sdk/redis-command-policy.yml`이 골라 쓰는 typed SDK의 명령 - 정책 정본이다. 거기 분류되지 않은 typed SDK 명령은 거절한다. 이 leaf의 semantic capability 어댑터를 위한 정책 - 파일이 아니다. -- `sdk.lettuce.operations`가 타입 있는 operation을 구현한다. 거기 있는 모든 것은 Lettuce에 닿는 유일한 이음매인 - `RedisCommandGateway`를 거치고, 모든 호출은 돌기 전에 `CommandPolicyGuard`의 허가를 받는다. operation에서 - driver를 직접 부르지 않는다. -- `sdk.cluster`는 client 쪽 slot 계산과 cluster 관찰을 가진다. `sdk.api`에만 의존하고 Lettuce를 import하지 - 않는다: slot을 명령을 만들기 전에 계산하므로 `CommandPolicyGuard`가 서버 redirect로 알게 되기 전에 cross-slot - 요청을 거절할 수 있다. -- `sdk.programmability`는 트랜잭션, 등록된 Lua script, 배포된 function 호출을 가진다. 호출 때 script 본문을 받지 - 않는다: catalog가 `EVAL`을 막고 `RedisScriptRegistry` digest의 `EVALSHA`만 닿을 수 있다. `FUNCTION LOAD`는 - 애플리케이션이 아니라 admin plane이다. -- 트랜잭션은 `WATCH`/`MULTI`/`EXEC`이고 **절대** 롤백하지 않는다. `TransactionResult`는 「실행됨」이나 「감시한 - 키가 바뀌어서 아무것도 돌지 않음」만 알리고, 이 패키지의 어떤 타입도 다른 뜻을 비치는 말을 주지 않는다. - 줄 세운 명령은 `QueuedReply`를 돌려주고, 커밋 전에 읽으면 던진다. 그 창 안에서 서버는 `+QUEUED`만 답했기 - 때문이다. 줄 세운 명령도 보통 명령과 같은 `CommandPolicyGuard` 허가를 지난다 — 트랜잭션은 guard를 피하는 길이 - 아니다 — 그리고 창은 던진 callback을 포함해 모든 출구에서 닫는다. `MULTI` 상태로 버려진 연결은 다음 호출자의 - 명령을 소리 없이 줄 세우기 때문이다. queue는 일부러 쓰기 전용이다: 창 안의 읽기로는 분기할 수 없으니, - 트랜잭션이 기대는 읽기는 그 앞에서 `WATCH` 아래에 둔다. -- `sdk.raw`는 승인된 raw 명령 gateway다. catalog가 `RAW_ONLY`로 표시했고 *그리고* 배포가 그 명령에 - `ApprovedRawCommand`를 등록했을 때만 닿을 수 있다. 보내기 전에 인자에서 키를 다시 파싱해 namespace를 검사한다. - 명령 이름을 문자열로 받는 메서드를 여기 더하지 않는다. -- `sdk.admin`은 읽기 전용 진단 plane이다. 자기 gateway(admin ACL 계정, 자기 연결)를 받고, catalog가 `ADMIN_ONLY`이자 - 읽기 전용으로 분류하지 않은 명령은 모두 거절하며, slow log나 client 목록이 인자·상대 주소·연결 이름을 싣지 - 않게 응답을 걸러 낸다. -- `sdk.extensions.*`는 Redis 8 모듈(JSON, Search, Time Series, Probabilistic)을 담는다. 모든 bean은 - `ifSupported(...)`로 만든다 — capability probe가 정하고, catalog 최소값은 앞 걸러내기일 뿐이다 — 그리고 모두 - `ExtensionCommandRunner`로 명령을 만들어 guard가 그 키를 본다. Search는 이것을 보여 주는 예외다: index는 키가 - 아니라서 그 이름은 `LettuceRedisSearchOperations`가 직접 namespace를 붙인다. -- `RedisSdkModuleBoundaryTest`(`redis-sdk` 안)가 `redis-sdk` 소스 루트를 scan해 내부 패키지 그래프, driver 가두기, - 아무 문자열 명령 surface 없음, 설계한 모듈 목록을 강제한다. -- 설계를 다시 보지 않고 바꾸면 안 되는 결정: 한계 없는 `entries`, `members`, `rangeAll`, `keys` 없음. 선택 사항인 - R2 허가·예산 없음. 아무 명령 문자열을 받는 overload 없음. timeout 뒤 멱등이 아닌 쓰기의 자동 재시도 없음. - metric이나 trace tag에 실제 키 없음. - -## 경계 - -- 허용 의존 edge는 이 모듈의 `src/config/architecture/modules.json` 항목에서만 온다. -- inbound 전송, 영속 엔티티·repository, bootstrap, 샘플 의존이 없다. -- cache 어댑터는 업무상 신선도, 자격, 도메인 대체 규칙을 정하지 않는다. -- Redis 물리 TTL은 인코딩한 hard 만료와 같아야 한다. 미래·손상 schema가 보통 miss로 뭉개지면 안 된다. -- application·domain 코드는 raw Redis 키, 명령, Lua·Function 이름, SDK 객체, topology, 연결 타입을 받으면 안 된다. -- cache의 fail-open 동작을 session, 멱등성, 엄격한 quota, lease, fencing에 다시 쓰면 안 된다. -- rate-limit 조립은 `app.cache.redis`, 그 연결, 외부 client 모드, 실패하면 열리는 뜻을 다시 쓰면 안 된다. v1은 - 조율 role이고 실패하면 닫히는 것뿐이다. -- standalone runtime·cache 서비스 lane은 R1 증거일 뿐이다. Sentinel·Cluster, TLS·ACL, 영속·재시작, eviction, 장애 - 증거는 R2를 위해 따로 필요하다. - -## 테스트 - -이 모듈만 보는 시험은 semantic 어댑터를 `testFixtures(project(':adapter:outbound:redis-runtime'))`의 -`InMemorySemanticRedisCommands`에 대고 돌린다. `SemanticRedisCommands`의 유일한 fake이고, `StubRedisRuntimeClient`를 -거쳐 쓴다. R1·R2 승격에는 따로 실제 Redis 서비스 lane이 필요하다. 그 lane을 골랐으면 소리 없이 건너뛰면 안 된다. - -실제 서버 lane이 둘 있다. `redisContainerContractTest`(integration category, `integrationCheck`에만 있다 — 이 leaf의 -`mainCheck`에도 있었을 때는 main push마다 두 번 돌았다)는 Testcontainers로 자기 Redis를 띄운다 — -`config/testing/container-images.properties`의 `redis` image이고 `compose/redis/acl/lane-fixture-accounts.acl`을 -읽어 들인다 — 그리고 `LiveRedisCacheRegionContractTest`, `LiveRedisDistributedLeaseContractTest`, -`LiveRedisIdempotencyStoreContractTest`(메모리 fake도 통과하는 `application-core` 포트 계약), -`LiveRedisSemanticPortsTest`, `LiveRedisSemanticScriptAclProbeTest`를 돌린다. 건너뛰기가 있으면 실패한다 -(2026-11-01부터). 멱등성 계약은 2026-11-03까지 명시할 때만 도는 topology lane에만 있었다. 그래서 Lua 상태 기계의 -낡은 handle, 갱신 거절, 재시도 경우가 어느 게이트에서도 실제 서버에 닿지 않았다. `RedisTestContainer`는 그 lane이 -ACL 파일을 이름으로 댈 때만 서버를 띄운다. - -`redisTopologyTest`는 외부 topology lane이고 `ca.redis-topology-lane`으로 선언한다. 이 leaf는 `standalone`과 -`cluster`(`LiveRedisSemanticPortsTest`, `LiveRedisSemanticScriptAclProbeTest`)를 선언한다. `redis-runtime`과 -`redis-sdk`는 자기 클래스에 대해 자기 lane을 선언한다. 고를 때만 돌고 실패하면 닫힌다: 모드는 `standalone`, -`sentinel`, `cluster`, `tls` 중 이 leaf가 선언한 것이어야 하고, endpoint 속성이 있어야 하며(`sentinel`은 -`redis.topology.master`가, `tls`는 `redis.topology.trust-material`이 더 필요하다), 시험을 하나도 찾지 못하거나 -돌리지 않은 실행은 실패하고(그것은 이 leaf가 아니라 규약이 가진다), leaf가 `redisTopologyLane`에 적은 클래스가 -실제로 돌았어야 하며, 건너뛴 시험은 실행한 것으로 세지 않고 실행을 실패시킨다. `tls`는 배포 모드가 아니라 -lane이다 — 모양은 standalone이고 태스크가 그렇게 대응시킨다. 검증하는 것이 전송이기 때문이다. - -예전 검사 둘은 없어졌다. 시험 소스에서 글자 그대로 `@Tag("redis-topology")`를 찾는 scan은 -`failOnNoDiscoveredTests`가 이미 내는 실패의 메시지를 낫게 할 뿐이었고, 같은 글을 담은 주석으로도 만족됐다. 손으로 -관리하던 모드별 실행 수 하한(20/20/24/4)은 경우를 더하거나 뺄 때마다 고쳐야 했고, 그것이 잡는 「덮는 범위가 -줄었다」는 런타임·배포·데이터·보안·컴파일 실패가 아니다. - -## 조립 - -`RedisRuntimeAutoConfiguration`은 이제 `:adapter:outbound:redis-runtime`의 것이다. Redis 설정과 공용 runtime 기반이 -생기는 유일한 곳이고, `app.redis.enabled`(env `APP_REDIS_ENABLED`, 기본 `true` — 모듈이 있으면 켜진다)가 true인 -동안에만 있다. topology client, 연결 owner, health contributor를 만든다. 이 leaf의 `RedisCapabilityConfig`(자기 -`AutoConfiguration.imports`)가 그 runtime 위에 semantic 포트를 조립한다. - -골라 쓰는 `:adapter:outbound:redis-sdk`는 출하하는 애플리케이션이 자동으로 조립하지 않는다. 그 -`RedisStartupProbe`는 라이브러리 API이고 숨은 운영 guard가 아니다. 특히 `APP_REDIS_ACKNOWLEDGED_WRITE_LOSS_ACCEPTED` -스위치는 없다: 그 거래를 받아들이는 것은 운영 호출자가 없는 공개 설정이 아니라 probe를 부르는 곳의 명시한 인자여야 -한다. - -모든 capability는 `CapabilityKeyspace`를 거쳐 `app.redis.namespace`의 namespace 하나 — -`{environment}:{service}:{domain}` — 아래에 키를 만든다. capability에 자기 접두어 token을 주지 않는다: capability 넷이 -각자 자유 문자열 둘을 이어 붙였더니 키 모양이 넷이 됐고, 배포의 ACL pattern은 그중 어느 것과도 맞지 않았다. - -lane은 서로 다른 계정으로 인증한다. `RedisLane.account()`가 lane의 `RedisAccount`를 이름으로 대고, topology factory는 -*설정한* 계정마다 client를 하나 만든다 — 그래서 계정이 하나인 배포는 여전히 client 하나와 event loop 하나만 가진다. -`SCRIPT` lane이 그것이 있는 이유다: `SCRIPT LOAD`와 `EVALSHA`는 advanced 계정의 것이라서, cache 항목을 읽는 계정은 -script를 실행할 수 없다. - -cache의 조건부 쓰기는 같은 계정이지만 자기 lane `CacheScriptLane.CACHE_SCRIPT`에서 돈다 -(`app.capabilities.cache.maximum-script-connections`, `RedisCacheConfig`가 `RedisLaneContribution`으로 기여한다). -`SCRIPT`로 되돌리지 않는다: 그 lane은 멱등성·rate-limit·lease의 예산이고, 부하를 받는 cache가 그것을 가져가면 -안 된다(2026-11-03에 정함). lane마다 기다림, 거절, 재연결은 `redis-runtime`의 meter(`RedisLaneMetrics`, `redis.lane.*`, -tag `lane`)이다. 그래서 cache가 `SCRIPT`를 쓰지 않는지는 짐작이 아니라 조회로 안다. `DEGRADED` health 순서는 -`redis-runtime`과 함께 나가고, 그 leaf가 상태를 알린다(`config/module-defaults/redis-runtime.yml`). - -Cluster 트랜잭션은 노드 하나에서 돈다. 그래서 SDK의 `RedisTransactionRunner`는 감시한 키(또는 명시한 -`RedisSlotTag`)에서 routing 키를 끌어내고, 그 slot을 가진 노드에서 키의 주인에 고정된 `RedisSdkLane.TRANSACTION`을 -빌린다. route된 lease는 pool에 두지 않는다: pool에 둔 연결은 앞 호출자의 노드에 고정되어 있다. - -설정 바인딩은 capability 기준 4(접두어 하나, `StrictSettingsBinder`)의 기록된 예외다(2026-11-03에 정함): -`app.redis.*`는 `redis-runtime`이 setter와 `validate()`로 바인딩한다. 그 leaf는 프로젝트 의존이 없어서 -`StrictSettingsBinder`(support)에 닿을 수 없기 때문이다. `app.capabilities.*`(cache, lease, rate-limit provider)는 이 -leaf가 공용 capability 선택 루트 아래에서 엄격하게 바인딩한다. `app.rate-limit.*`은 이 leaf가 읽기만 하는 HTTP -경계의 스위치다. 키 이름을 바꾸면 동작 이득 없이 모든 배포의 환경이 깨지니 세 트리를 그대로 둔다. 새 Redis 설정은 -그중 하나에 넣고, 네 번째 트리를 만들지 않는다. - -`RedisRuntimeSettings`에는 클래스 수준 `@ConfigurationProperties`를 달면 안 된다: `RedisRuntimeAutoConfiguration`이 -그것을 바인딩하므로 `APP_REDIS_ENABLED=false`이면 Redis 설정을 하나도 바인딩하지 않는다. 이 패키지에 닿는 -properties scan은 그래도 그것을 바인딩하게 된다(bootstrap의 `@ConfigurationPropertiesScan`은 -`dev.caskeleton.bootstrap.*` 패키지만 적는다). role 선택자(cache 바인딩, session 인증 모드, 멱등성·lease·rate-limit -provider)는 어떤 capability를 조립할지 고른다. 그중 어느 것도 Redis를 켜지 않고, 전역 스위치가 꺼져 있으면 이 -모듈은 bean을 하나도 기여하지 않는다. +@AGENTS.md diff --git a/src/adapter/outbound/fileserver/AGENTS.md b/src/adapter/outbound/fileserver/AGENTS.md new file mode 100644 index 00000000..fbece082 --- /dev/null +++ b/src/adapter/outbound/fileserver/AGENTS.md @@ -0,0 +1,41 @@ +# adapter:outbound:fileserver — 모듈 규칙 + +## 등록 정보 + +- 모듈 ID: `adapter-outbound-fileserver` +- Gradle 경로: `:adapter:outbound:fileserver` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:fileserver:test --console=plain` +- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. +- registry 정본: `src/config/architecture/modules.json`. + +패키지 루트: `dev.caskeleton.adapter.outbound.fileserver.platform`. HTTP 파일 서버 플랫폼의 driven +(outbound) 어댑터다: `application-fileserver` 포트(내용 저장, 검증, 식별자, 감사, metric)를 구현한다. +설계 근거는 [README.md](README.md)에 있다. + +## 책임 + +- `application-fileserver` 포트 뒤의 로컬 파일 시스템 내용 저장, 검증, 식별자, 감사, metric. +- `app.fileserver-platform.*`(기본 꺼짐)으로만 켠다. 이 leaf의 `AutoConfiguration.imports`에 등록한 + `platform.autoconfigure.FileserverCapabilityAutoConfiguration`에서 켜진다. +- 자세한 전송·보안·운영 계약은 `docs/fileserver/` 아래에 있다. 인증된 동작은 + `docs/fileserver/support-matrix.md`가 적는다. + +## 허용 + +- 프로젝트 의존: 정본은 `src/config/architecture/modules.json`의 `adapter-outbound-fileserver` 항목이고 + `src/build.gradle`이 강제한다. `:domain-core`는 없다. +- 외부 런타임: JDK 파일 시스템, `spring-boot-autoconfigure`, `micrometer-core`, `slf4j-api`. + +## 금지 + +- inbound 어댑터, 영속, `app-bootstrap`(ArchUnit `OUTBOUND_ADAPTERS_*` 규칙 묶음). +- 파일 시스템·stream·프레임워크·provider 타입을 application 포트 너머로 새게 하기. +- `docs/fileserver/support-matrix.md`가 적지 않은 플랫폼 기능을 구현됐다고 내세우기. +- 줄 안에 완전한 이름으로 쓴 타입 참조, 파일 하나에 공개 최상위 타입 둘 이상. + +## 테스트 + +```bash +cd src +./gradlew :adapter:outbound:fileserver:check +``` diff --git a/src/adapter/outbound/fileserver/CLAUDE.md b/src/adapter/outbound/fileserver/CLAUDE.md index fbece082..43c994c2 100644 --- a/src/adapter/outbound/fileserver/CLAUDE.md +++ b/src/adapter/outbound/fileserver/CLAUDE.md @@ -1,41 +1 @@ -# adapter:outbound:fileserver — 모듈 규칙 - -## 등록 정보 - -- 모듈 ID: `adapter-outbound-fileserver` -- Gradle 경로: `:adapter:outbound:fileserver` -- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:fileserver:test --console=plain` -- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. -- registry 정본: `src/config/architecture/modules.json`. - -패키지 루트: `dev.caskeleton.adapter.outbound.fileserver.platform`. HTTP 파일 서버 플랫폼의 driven -(outbound) 어댑터다: `application-fileserver` 포트(내용 저장, 검증, 식별자, 감사, metric)를 구현한다. -설계 근거는 [README.md](README.md)에 있다. - -## 책임 - -- `application-fileserver` 포트 뒤의 로컬 파일 시스템 내용 저장, 검증, 식별자, 감사, metric. -- `app.fileserver-platform.*`(기본 꺼짐)으로만 켠다. 이 leaf의 `AutoConfiguration.imports`에 등록한 - `platform.autoconfigure.FileserverCapabilityAutoConfiguration`에서 켜진다. -- 자세한 전송·보안·운영 계약은 `docs/fileserver/` 아래에 있다. 인증된 동작은 - `docs/fileserver/support-matrix.md`가 적는다. - -## 허용 - -- 프로젝트 의존: 정본은 `src/config/architecture/modules.json`의 `adapter-outbound-fileserver` 항목이고 - `src/build.gradle`이 강제한다. `:domain-core`는 없다. -- 외부 런타임: JDK 파일 시스템, `spring-boot-autoconfigure`, `micrometer-core`, `slf4j-api`. - -## 금지 - -- inbound 어댑터, 영속, `app-bootstrap`(ArchUnit `OUTBOUND_ADAPTERS_*` 규칙 묶음). -- 파일 시스템·stream·프레임워크·provider 타입을 application 포트 너머로 새게 하기. -- `docs/fileserver/support-matrix.md`가 적지 않은 플랫폼 기능을 구현됐다고 내세우기. -- 줄 안에 완전한 이름으로 쓴 타입 참조, 파일 하나에 공개 최상위 타입 둘 이상. - -## 테스트 - -```bash -cd src -./gradlew :adapter:outbound:fileserver:check -``` +@AGENTS.md diff --git a/src/adapter/outbound/fileserver/README.md b/src/adapter/outbound/fileserver/README.md index 39e29bfc..f1bfaf72 100644 --- a/src/adapter/outbound/fileserver/README.md +++ b/src/adapter/outbound/fileserver/README.md @@ -5,7 +5,7 @@ HTTP 파일 서버 플랫폼의 outbound(driven) 어댑터다. 패키지 루트: 시스템 내용 저장, 업로드 검증, 식별자, 감사, metric. 허용·금지 운영 의존 정책은 `src/config/architecture/modules.json`의 `adapter-outbound-fileserver` 항목이 -가진다. 루트 Gradle 검증이 그 registry를 읽는다. 모듈 규칙은 [CLAUDE.md](CLAUDE.md)에 있다. +가진다. 루트 Gradle 검증이 그 registry를 읽는다. 모듈 규칙은 [AGENTS.md](AGENTS.md)에 있다. 전송·보안·설정·운영 계약은 `docs/fileserver/`에 있다. 이 파일 서버 플랫폼과 Object Storage 중 무엇을 고를지에 대한 저장소 단위 선택은 diff --git a/src/adapter/outbound/httpclient/AGENTS.md b/src/adapter/outbound/httpclient/AGENTS.md new file mode 100644 index 00000000..f1e67aab --- /dev/null +++ b/src/adapter/outbound/httpclient/AGENTS.md @@ -0,0 +1,86 @@ +# adapter:outbound:httpclient — HTTP client 플랫폼 + +## 등록 정보 + +- 모듈 ID: `adapter-outbound-httpclient` +- Gradle 경로: `:adapter:outbound:httpclient` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:httpclient:test --console=plain` +- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. +- registry 정본: `src/config/architecture/modules.json`. + +패키지 루트: `dev.caskeleton.adapter.outbound.httpclient`. + +## 설계 정본 + +구현은 `docs/design/2026-08-08-httpclient-platform-design.md`를 따른다. 설계는 Gradle 모듈 19개를 따로 두는 +것을 전제한다. 이 저장소의 실패하면 닫히는 registry가 그 배치보다 앞서므로, 그 모듈들은 여기서 **패키지**다. +그 대응과 그 밖에 일부러 바꾼 것은 모두 `docs/httpclient/repository-adaptation.md`에 적혀 있다. 타입을 다른 +패키지로 옮기기 전에 그것을 읽는다. + +## 책임 + +- 공개 호출 surface를 가진다: H1 typed service client(기본), H2 generic exchange, H3 dynamic target. H4 native + engine 접근은 `apache`, `jdk`, `http3` 안에 머문다. +- blocking만: 호출은 `RestClient`를 거쳐 호출자의 (virtual) 스레드에서 돈다. reactive stack(`WebClient`, + Reactor Netty)은 2026-09-25 소유자 결정으로 지웠다. 다시 들이지 않는다. +- Named Client Profile, runtime generation, transport SPI, deadline, 증거 기반 재시도, resilience, 인증, TLS, + SSRF 방어, streaming lifecycle, 관측을 가진다. +- 외부 HTTP 호출을 application·domain 포트 뒤에 맞춘다. +- 공용 outbound 관심사는 `adapter:outbound:support`를 다시 쓴다. + +## 패키지 경계 + +`HttpClientModuleBoundaryTest`와 `PublicApiArchitectureTest`가 설계의 모듈 표를 강제한다: + +- `api`는 플랫폼 안의 다른 어떤 것에도, Spring·Apache·Jetty·Resilience4j 타입에도 의존하지 않는다. +- `profile`은 공개적으로 `api`에만 의존한다. +- transport 패키지는 gateway로 거슬러 닿지 않는다. +- `resilience`는 transport에 의존하지 않는다 — 재시도 자격은 transport와 무관하다. +- 운영 패키지는 다시 쓰는 testkit에 의존하지 않는다. testkit은 Gradle `testFixtures` + (`src/testFixtures/java`)에 있고, 보통 시험, integration·performance lane, JMH가 명시적으로 쓴다. 그 의존은 + test-fixture·test 설정에 머물러서 운영 코드는 여전히 닿지 못한다. 경계 규칙이 import하는 「운영 클래스」의 + 유일한 정의는 `PlatformClasses`다. +- Stable 코드는 `http3`를 참조하지 않는다. +- 어떤 클래스도 `org.springframework.web.service.registry`나 `RestTemplate`를 쓰지 않는다. + +## 경계 + +- 허용 의존 edge는 이 모듈의 `src/config/architecture/modules.json` 항목에서만 온다. +- inbound controller·DTO, 영속, bootstrap, 샘플 의존이 없다. +- 재시도와 circuit breaker 코드는 기술적 resilience다. 업무 보상과 유스케이스 순서는 application·domain 계층에 + 남는다. +- application·domain 코드는 이 모듈의 gateway, operation descriptor, URI 타입, Spring HTTP 타입, engine client, + 재시도 타입, wire DTO를 import하면 안 된다. 그 방향은 `config/architecture/modules.json`의 저장소 단위 Gradle + 의존 게이트가 강제한다. 이 leaf의 ArchUnit 규칙은 leaf 안의 경계만 다룬다. +- 보통 호출은 등록된 profile과 profile 기준 template을 쓴다. 절대 URL은 H3만 쓴다. +- 조립은 `dev.caskeleton.adapter.outbound.httpclient.autoconfigure` 아래에서 capability가 가진다: profile 바인딩, + 기동 검증, transport 등록, service gateway, dynamic target, actuator endpoint가 이 leaf에 있고 Boot 자동 구성 + metadata로 나간다. `HttpClientPlatformAutoConfiguration`은 `app.httpclient.enabled=true`일 때만 켜진다. + 스위치가 꺼져 있으면 capability에는 bean이 하나도 없다 — 빈 registry가 아니라 아무것도 없다. +- `app-bootstrap`은 운영 코드에서 HTTP client 구현이나 자동 구성 클래스를 import하면 안 된다. 빌드에 넣을지는 + 이 런타임 켜기 스위치와 따로 정한다. + +## 테스트 + +기본 lane: `./gradlew :adapter:outbound:httpclient:test`. 추가 lane은 모두 실패하면 닫힌다: + +| lane | 용도 | +|---|---| +| `httpClientStableContractTest` | Apache와 JDK에 걸친 semantic 계약 하나 | +| `httpClientSecurityTest` | SSRF 표, credential 걷어내기, tag cardinality | +| `httpClientFailureInjectionTest` | Toxiproxy 장애. **Docker가 필요하고 없으면 실패한다** | +| `httpClientPerformanceTest` | pool, streaming, 재시도, 교체의 자원 한계 | +| `spring62ApiSurfaceScan` | Spring 6.2 API surface 가두기 | +| `spring70CompatibilityTest` | 저장소 기준 버전 위의 계약 suite | +| `jmh` | 호출당 부담 benchmark | + +고른 lane은 소리 없이 건너뛰지 않는다: 장애 lane은 Docker가 없으면 던지고, 계약 lane은 transport 선택이 +비었거나 모르는 것이면 던지고, performance lane은 실행마다 모든 한계를 단언한다 — 빌드가 +`performance.assertions.enabled`에 `true` 아닌 값을 넣거나 그 시험 하나가 건너뛰어지면 strict lane 규약이 +실패시킨다. + +transport 포트(`BlockingTransportProvider`)에는 test fixtures에 추상 계약 하나 +`testkit/BlockingTransportProviderContract`가 있다. engine은 실제 socket 위에서 그것을 통과하고 +(`StableTransportProviderContractTest`, 계약 lane, 고른 transport마다 한 번), gateway 시험이 딛고 서는 각본 +fake는 기본 lane에서 그것을 통과한다(`ScriptedTransportContractTest`). 새 transport나 `ScriptedTransport`의 +변경은 사본이 아니라 같은 클래스를 상속한다(AGENTS.md 규칙 6). diff --git a/src/adapter/outbound/httpclient/CLAUDE.md b/src/adapter/outbound/httpclient/CLAUDE.md index f1e67aab..43c994c2 100644 --- a/src/adapter/outbound/httpclient/CLAUDE.md +++ b/src/adapter/outbound/httpclient/CLAUDE.md @@ -1,86 +1 @@ -# adapter:outbound:httpclient — HTTP client 플랫폼 - -## 등록 정보 - -- 모듈 ID: `adapter-outbound-httpclient` -- Gradle 경로: `:adapter:outbound:httpclient` -- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:httpclient:test --console=plain` -- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. -- registry 정본: `src/config/architecture/modules.json`. - -패키지 루트: `dev.caskeleton.adapter.outbound.httpclient`. - -## 설계 정본 - -구현은 `docs/design/2026-08-08-httpclient-platform-design.md`를 따른다. 설계는 Gradle 모듈 19개를 따로 두는 -것을 전제한다. 이 저장소의 실패하면 닫히는 registry가 그 배치보다 앞서므로, 그 모듈들은 여기서 **패키지**다. -그 대응과 그 밖에 일부러 바꾼 것은 모두 `docs/httpclient/repository-adaptation.md`에 적혀 있다. 타입을 다른 -패키지로 옮기기 전에 그것을 읽는다. - -## 책임 - -- 공개 호출 surface를 가진다: H1 typed service client(기본), H2 generic exchange, H3 dynamic target. H4 native - engine 접근은 `apache`, `jdk`, `http3` 안에 머문다. -- blocking만: 호출은 `RestClient`를 거쳐 호출자의 (virtual) 스레드에서 돈다. reactive stack(`WebClient`, - Reactor Netty)은 2026-09-25 소유자 결정으로 지웠다. 다시 들이지 않는다. -- Named Client Profile, runtime generation, transport SPI, deadline, 증거 기반 재시도, resilience, 인증, TLS, - SSRF 방어, streaming lifecycle, 관측을 가진다. -- 외부 HTTP 호출을 application·domain 포트 뒤에 맞춘다. -- 공용 outbound 관심사는 `adapter:outbound:support`를 다시 쓴다. - -## 패키지 경계 - -`HttpClientModuleBoundaryTest`와 `PublicApiArchitectureTest`가 설계의 모듈 표를 강제한다: - -- `api`는 플랫폼 안의 다른 어떤 것에도, Spring·Apache·Jetty·Resilience4j 타입에도 의존하지 않는다. -- `profile`은 공개적으로 `api`에만 의존한다. -- transport 패키지는 gateway로 거슬러 닿지 않는다. -- `resilience`는 transport에 의존하지 않는다 — 재시도 자격은 transport와 무관하다. -- 운영 패키지는 다시 쓰는 testkit에 의존하지 않는다. testkit은 Gradle `testFixtures` - (`src/testFixtures/java`)에 있고, 보통 시험, integration·performance lane, JMH가 명시적으로 쓴다. 그 의존은 - test-fixture·test 설정에 머물러서 운영 코드는 여전히 닿지 못한다. 경계 규칙이 import하는 「운영 클래스」의 - 유일한 정의는 `PlatformClasses`다. -- Stable 코드는 `http3`를 참조하지 않는다. -- 어떤 클래스도 `org.springframework.web.service.registry`나 `RestTemplate`를 쓰지 않는다. - -## 경계 - -- 허용 의존 edge는 이 모듈의 `src/config/architecture/modules.json` 항목에서만 온다. -- inbound controller·DTO, 영속, bootstrap, 샘플 의존이 없다. -- 재시도와 circuit breaker 코드는 기술적 resilience다. 업무 보상과 유스케이스 순서는 application·domain 계층에 - 남는다. -- application·domain 코드는 이 모듈의 gateway, operation descriptor, URI 타입, Spring HTTP 타입, engine client, - 재시도 타입, wire DTO를 import하면 안 된다. 그 방향은 `config/architecture/modules.json`의 저장소 단위 Gradle - 의존 게이트가 강제한다. 이 leaf의 ArchUnit 규칙은 leaf 안의 경계만 다룬다. -- 보통 호출은 등록된 profile과 profile 기준 template을 쓴다. 절대 URL은 H3만 쓴다. -- 조립은 `dev.caskeleton.adapter.outbound.httpclient.autoconfigure` 아래에서 capability가 가진다: profile 바인딩, - 기동 검증, transport 등록, service gateway, dynamic target, actuator endpoint가 이 leaf에 있고 Boot 자동 구성 - metadata로 나간다. `HttpClientPlatformAutoConfiguration`은 `app.httpclient.enabled=true`일 때만 켜진다. - 스위치가 꺼져 있으면 capability에는 bean이 하나도 없다 — 빈 registry가 아니라 아무것도 없다. -- `app-bootstrap`은 운영 코드에서 HTTP client 구현이나 자동 구성 클래스를 import하면 안 된다. 빌드에 넣을지는 - 이 런타임 켜기 스위치와 따로 정한다. - -## 테스트 - -기본 lane: `./gradlew :adapter:outbound:httpclient:test`. 추가 lane은 모두 실패하면 닫힌다: - -| lane | 용도 | -|---|---| -| `httpClientStableContractTest` | Apache와 JDK에 걸친 semantic 계약 하나 | -| `httpClientSecurityTest` | SSRF 표, credential 걷어내기, tag cardinality | -| `httpClientFailureInjectionTest` | Toxiproxy 장애. **Docker가 필요하고 없으면 실패한다** | -| `httpClientPerformanceTest` | pool, streaming, 재시도, 교체의 자원 한계 | -| `spring62ApiSurfaceScan` | Spring 6.2 API surface 가두기 | -| `spring70CompatibilityTest` | 저장소 기준 버전 위의 계약 suite | -| `jmh` | 호출당 부담 benchmark | - -고른 lane은 소리 없이 건너뛰지 않는다: 장애 lane은 Docker가 없으면 던지고, 계약 lane은 transport 선택이 -비었거나 모르는 것이면 던지고, performance lane은 실행마다 모든 한계를 단언한다 — 빌드가 -`performance.assertions.enabled`에 `true` 아닌 값을 넣거나 그 시험 하나가 건너뛰어지면 strict lane 규약이 -실패시킨다. - -transport 포트(`BlockingTransportProvider`)에는 test fixtures에 추상 계약 하나 -`testkit/BlockingTransportProviderContract`가 있다. engine은 실제 socket 위에서 그것을 통과하고 -(`StableTransportProviderContractTest`, 계약 lane, 고른 transport마다 한 번), gateway 시험이 딛고 서는 각본 -fake는 기본 lane에서 그것을 통과한다(`ScriptedTransportContractTest`). 새 transport나 `ScriptedTransport`의 -변경은 사본이 아니라 같은 클래스를 상속한다(AGENTS.md 규칙 6). +@AGENTS.md diff --git a/src/adapter/outbound/identifier/AGENTS.md b/src/adapter/outbound/identifier/AGENTS.md new file mode 100644 index 00000000..0d021b3a --- /dev/null +++ b/src/adapter/outbound/identifier/AGENTS.md @@ -0,0 +1,53 @@ +# adapter:outbound:identifier — IO 없는 기반 capability 어댑터 + +## 등록 정보 + +- 모듈 ID: `adapter-outbound-identifier` +- Gradle 경로: `:adapter:outbound:identifier` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:identifier:test --console=plain` +- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. +- registry 정본: `src/config/architecture/modules.json`. + +패키지 루트: `dev.caskeleton.adapter.outbound.identifier`. + +예전에 코드 주석에 두던 설계 결정(알고리즘 정본, salt 출처, 빌드 선택)은 [README.md](README.md)에 있다. + +## 책임 + +- `HmacUserPrincipalPseudonymizer` — `UserPrincipalPseudonymizerPort` 구현(UTF-8 principal의 HMAC-SHA-256, + 소문자 hex). +- `UuidV7DurableOperationIdFactory` — `DurableOperationIdFactory` 구현(`uuid-creator`로 만든 UUIDv7). + operation id는 제출 이벤트의 id이기도 하고, 메시징 플랫폼의 message id는 UUIDv7만 받는다. + `composition:durable-operation`이 배선한다. +- leaf 이름은 「identifier」다. 범용 시계·난수 출처는 여기 없다. Gradle 경로와 쓰는 쪽이 이 이름을 쓰니 + 이름을 그대로 둔다(README). +- 배선은 이 leaf가 아니라 `composition/service-runtime`(`PseudonymizationConfig`)이다. + +## 허용 + +[build.gradle](build.gradle)에 선언한다. registry 항목이 정본이다. + +- `:application-core` — 두 클래스가 구현하는 포트. +- `:shared-contract`, `HmacSha256`만. 가명은 principal의 hex HMAC이다. + `HmacUserPrincipalPseudonymizerVectorTest`가 그것을 JVM 밖에서 계산한 벡터에 고정한다. 릴리스 전후에 쓴 + 로그를 이 값으로 잇기 때문이다. +- `:domain-core` — 기능의 서버 지정 id 어댑터가 여기서 그 도메인 `*IdFactory` 포트를 구현한다(registry + edge `adapter:outbound:identifier -> domain-core`, `docs/manual/02-new-feature.md`). +- `com.github.f4b6a3:uuid-creator`(`libs.uuid.creator`) — `UuidV7DurableOperationIdFactory`의 UUIDv7. + +## 금지 + +- 영속·web 기술(JPA/Hibernate/Spring Data/Spring Web) — ArchUnit + `IDENTIFIER_ADAPTER_DOES_NOT_DEPEND_ON_OTHER_ADAPTERS_OR_BOOTSTRAP`와 registry 방향 게이트가 막는다. +- inbound 어댑터, 영속 어댑터, 다른 outbound leaf, `app-bootstrap`. +- 외부 IO(HTTP / 메시징 / cache / DB) — 그것은 IO를 하는 outbound 어댑터 leaf에 둔다. + +## 테스트 + +Spring context 없는 순수 단위 시험: `HmacUserPrincipalPseudonymizerTest`(RFC 4231 known-answer 벡터 포함), +`HmacUserPrincipalPseudonymizerVectorTest`, `UuidV7DurableOperationIdFactoryTest`. + +```bash +cd src +./gradlew :adapter:outbound:identifier:test --console=plain +``` diff --git a/src/adapter/outbound/identifier/CLAUDE.md b/src/adapter/outbound/identifier/CLAUDE.md index 0d021b3a..43c994c2 100644 --- a/src/adapter/outbound/identifier/CLAUDE.md +++ b/src/adapter/outbound/identifier/CLAUDE.md @@ -1,53 +1 @@ -# adapter:outbound:identifier — IO 없는 기반 capability 어댑터 - -## 등록 정보 - -- 모듈 ID: `adapter-outbound-identifier` -- Gradle 경로: `:adapter:outbound:identifier` -- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:identifier:test --console=plain` -- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. -- registry 정본: `src/config/architecture/modules.json`. - -패키지 루트: `dev.caskeleton.adapter.outbound.identifier`. - -예전에 코드 주석에 두던 설계 결정(알고리즘 정본, salt 출처, 빌드 선택)은 [README.md](README.md)에 있다. - -## 책임 - -- `HmacUserPrincipalPseudonymizer` — `UserPrincipalPseudonymizerPort` 구현(UTF-8 principal의 HMAC-SHA-256, - 소문자 hex). -- `UuidV7DurableOperationIdFactory` — `DurableOperationIdFactory` 구현(`uuid-creator`로 만든 UUIDv7). - operation id는 제출 이벤트의 id이기도 하고, 메시징 플랫폼의 message id는 UUIDv7만 받는다. - `composition:durable-operation`이 배선한다. -- leaf 이름은 「identifier」다. 범용 시계·난수 출처는 여기 없다. Gradle 경로와 쓰는 쪽이 이 이름을 쓰니 - 이름을 그대로 둔다(README). -- 배선은 이 leaf가 아니라 `composition/service-runtime`(`PseudonymizationConfig`)이다. - -## 허용 - -[build.gradle](build.gradle)에 선언한다. registry 항목이 정본이다. - -- `:application-core` — 두 클래스가 구현하는 포트. -- `:shared-contract`, `HmacSha256`만. 가명은 principal의 hex HMAC이다. - `HmacUserPrincipalPseudonymizerVectorTest`가 그것을 JVM 밖에서 계산한 벡터에 고정한다. 릴리스 전후에 쓴 - 로그를 이 값으로 잇기 때문이다. -- `:domain-core` — 기능의 서버 지정 id 어댑터가 여기서 그 도메인 `*IdFactory` 포트를 구현한다(registry - edge `adapter:outbound:identifier -> domain-core`, `docs/manual/02-new-feature.md`). -- `com.github.f4b6a3:uuid-creator`(`libs.uuid.creator`) — `UuidV7DurableOperationIdFactory`의 UUIDv7. - -## 금지 - -- 영속·web 기술(JPA/Hibernate/Spring Data/Spring Web) — ArchUnit - `IDENTIFIER_ADAPTER_DOES_NOT_DEPEND_ON_OTHER_ADAPTERS_OR_BOOTSTRAP`와 registry 방향 게이트가 막는다. -- inbound 어댑터, 영속 어댑터, 다른 outbound leaf, `app-bootstrap`. -- 외부 IO(HTTP / 메시징 / cache / DB) — 그것은 IO를 하는 outbound 어댑터 leaf에 둔다. - -## 테스트 - -Spring context 없는 순수 단위 시험: `HmacUserPrincipalPseudonymizerTest`(RFC 4231 known-answer 벡터 포함), -`HmacUserPrincipalPseudonymizerVectorTest`, `UuidV7DurableOperationIdFactoryTest`. - -```bash -cd src -./gradlew :adapter:outbound:identifier:test --console=plain -``` +@AGENTS.md diff --git a/src/adapter/outbound/identifier/README.md b/src/adapter/outbound/identifier/README.md index 95acbb3d..d338f02c 100644 --- a/src/adapter/outbound/identifier/README.md +++ b/src/adapter/outbound/identifier/README.md @@ -3,7 +3,7 @@ 이 leaf의 main 코드는 `HmacUserPrincipalPseudonymizer`와 `UuidV7DurableOperationIdFactory` 두 클래스다. 패키지 루트: `dev.caskeleton.adapter.outbound.identifier`. -허용·금지 의존과 테스트 명령 같은 **모듈 규칙**은 [CLAUDE.md](CLAUDE.md)가 기준이다. 이 문서는 +허용·금지 의존과 테스트 명령 같은 **모듈 규칙**은 [AGENTS.md](AGENTS.md)가 기준이다. 이 문서는 설계 결정의 근거를 모은다. ## 이름과 내용이 다른 이유 (review 05-21) @@ -49,7 +49,7 @@ Spring 어노테이션이 없다. bean은 의존은 넷이다: `:application-core`(두 클래스가 구현하는 port), `:shared-contract`(`HmacSha256`), `:domain-core`(기능의 `*IdFactory` 구현 자리), `uuid-creator`(UUIDv7). 목록과 이유는 -[CLAUDE.md](CLAUDE.md) Allowed 절이 기준이다. +[AGENTS.md](AGENTS.md) Allowed 절이 기준이다. `:application-core`를 `implementation`으로 받는다. 이 leaf의 public 타입 시그니처에 application-core 타입이 드러나지만, 조립하는 쪽이 application-core를 이미 classpath에 갖고 있다. diff --git a/src/adapter/outbound/messaging-kafka/AGENTS.md b/src/adapter/outbound/messaging-kafka/AGENTS.md new file mode 100644 index 00000000..8434332e --- /dev/null +++ b/src/adapter/outbound/messaging-kafka/AGENTS.md @@ -0,0 +1,13 @@ +# adapter:outbound:messaging-kafka + +- 모듈 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는 + registry 항목에서만 온다. +- 시험: 켜기 시험(`./gradlew :adapter:outbound:messaging-kafka:test`)과 실제 Kafka lane + `messagingKafkaRelayIntegrationTest`(relay → bridge → broker record 바이트, `:integrationCheck`). +- 설계: `README.md`. diff --git a/src/adapter/outbound/messaging-kafka/CLAUDE.md b/src/adapter/outbound/messaging-kafka/CLAUDE.md index 7f2fa07a..43c994c2 100644 --- a/src/adapter/outbound/messaging-kafka/CLAUDE.md +++ b/src/adapter/outbound/messaging-kafka/CLAUDE.md @@ -1,13 +1 @@ -# adapter:outbound:messaging-kafka - -- 모듈 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/CLAUDE.md`)에 속한다. 여기 클래스를 두면 세 번째 자리가 생긴다. 허용 edge는 - registry 항목에서만 온다. -- 시험: 켜기 시험(`./gradlew :adapter:outbound:messaging-kafka:test`)과 실제 Kafka lane - `messagingKafkaRelayIntegrationTest`(relay → bridge → broker record 바이트, `:integrationCheck`). -- 설계: `README.md`. +@AGENTS.md diff --git a/src/adapter/outbound/messaging/AGENTS.md b/src/adapter/outbound/messaging/AGENTS.md new file mode 100644 index 00000000..bfd3277d --- /dev/null +++ b/src/adapter/outbound/messaging/AGENTS.md @@ -0,0 +1,46 @@ +# adapter:outbound:messaging — 메시징 어댑터 + +## 등록 정보 + +- 모듈 ID: `adapter-outbound-messaging` +- Gradle 경로: `:adapter:outbound:messaging` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:messaging:test --console=plain` +- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. +- registry 정본: `src/config/architecture/modules.json`. + +패키지 루트: `dev.caskeleton.adapter.outbound.messaging`. + +## 책임 + +- application·domain 포트 뒤에서 outbound 메시지 발행과 broker 연동을 구현한다. +- broker 설정, 꺼짐·안전 실패 기술 모드, outbox 발행 연결을 가진다. +- 조건 없이 하나만 있는 `Slf4jOutboxRelayFailureReportAdapter` bean으로 `OutboxRelayFailureReport`를 구조화해 + 남긴다. +- 공용 기술 관심사는 `adapter:outbound:support`를 다시 쓴다. + +## 경계 + +- 허용 의존 edge는 이 모듈의 `src/config/architecture/modules.json` 항목에서만 온다. +- inbound DTO·controller, 영속 repository·엔티티, bootstrap, 샘플 의존이 없다. +- 정해진 플랫폼 bridge는 `messaging-core-api`(`schema` 패키지도 담는다)에만 의존할 수 있다. + `platformbridge/` 아래에서 `messaging-runtime-core`, 전송 SPI 구현, broker SDK 타입을 import하지 않는다. +- 발행 경로는 하나다: `OutboxMessagePublishAdapter` → `IntegrationEventPublishPort` → 플랫폼 bridge. 옛 + `KafkaSender` / `MessageBroker` R0 이음매와 실패해도 열리는(fail-open) `MessagePublisher`는 정해진 outbox와 + 함께 지웠다(2026-09-28). 두 번째 경로를 다시 들이지 않는다. +- 정해진 producer identity는 명시한 `app.messaging.producer-id`다. `spring.application.name`, host, pod, + 프로세스 identity에서 끌어내지 않는다. 모듈이 켜져 있는데 bridge가 없으면 기동을 거절한다 — relay가 발행할 + 길이 없다. +- 템플릿의 `IntegrationEventEncoderPort`(`JsonIntegrationEventEncoder`)는 여기가 아니라 + `adapter:outbound:support`에 있다: 유스케이스는 append하기 전에 인코딩하는데, 이 모듈을 싣지 않는 조립도 + 있다. R1 contract·binding 컴파일러와 JSON Schema envelope 인코더는 2026-09-25에 지웠다 + (`docs/capability-status.md`). +- 주 classpath에 JSON Schema 엔진(NetworkNT)이 없다. 증거 manifest schema 검사와 capability card 검사 + (`release/`)는 이 leaf의 시험(`evidence/`)이다. snakeyaml은 시험에서만 쓴다(소유자 결정 2026-09-25). +- 유스케이스 순서나 업무 라우팅 정책을 broker 어댑터 안에 숨기지 않는다. +- `OutboxMessagePublishAdapter`는 위임만 하고 의존성 로그를 내지 않는다. 확정된 FAILED/DEAD 전이가 정해진 + ERROR 하나를 가진다. + +## 테스트 + +가짜 정해진 publisher로 단위·계약 시험을 쓴다. 이 모듈만 보는 시험은 실제 네트워크나 broker를 쓰지 않는다. +설정이 바뀌면 settings record에 바인딩·검증 시험을 더한다. diff --git a/src/adapter/outbound/messaging/CLAUDE.md b/src/adapter/outbound/messaging/CLAUDE.md index bfd3277d..43c994c2 100644 --- a/src/adapter/outbound/messaging/CLAUDE.md +++ b/src/adapter/outbound/messaging/CLAUDE.md @@ -1,46 +1 @@ -# adapter:outbound:messaging — 메시징 어댑터 - -## 등록 정보 - -- 모듈 ID: `adapter-outbound-messaging` -- Gradle 경로: `:adapter:outbound:messaging` -- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:messaging:test --console=plain` -- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. -- registry 정본: `src/config/architecture/modules.json`. - -패키지 루트: `dev.caskeleton.adapter.outbound.messaging`. - -## 책임 - -- application·domain 포트 뒤에서 outbound 메시지 발행과 broker 연동을 구현한다. -- broker 설정, 꺼짐·안전 실패 기술 모드, outbox 발행 연결을 가진다. -- 조건 없이 하나만 있는 `Slf4jOutboxRelayFailureReportAdapter` bean으로 `OutboxRelayFailureReport`를 구조화해 - 남긴다. -- 공용 기술 관심사는 `adapter:outbound:support`를 다시 쓴다. - -## 경계 - -- 허용 의존 edge는 이 모듈의 `src/config/architecture/modules.json` 항목에서만 온다. -- inbound DTO·controller, 영속 repository·엔티티, bootstrap, 샘플 의존이 없다. -- 정해진 플랫폼 bridge는 `messaging-core-api`(`schema` 패키지도 담는다)에만 의존할 수 있다. - `platformbridge/` 아래에서 `messaging-runtime-core`, 전송 SPI 구현, broker SDK 타입을 import하지 않는다. -- 발행 경로는 하나다: `OutboxMessagePublishAdapter` → `IntegrationEventPublishPort` → 플랫폼 bridge. 옛 - `KafkaSender` / `MessageBroker` R0 이음매와 실패해도 열리는(fail-open) `MessagePublisher`는 정해진 outbox와 - 함께 지웠다(2026-09-28). 두 번째 경로를 다시 들이지 않는다. -- 정해진 producer identity는 명시한 `app.messaging.producer-id`다. `spring.application.name`, host, pod, - 프로세스 identity에서 끌어내지 않는다. 모듈이 켜져 있는데 bridge가 없으면 기동을 거절한다 — relay가 발행할 - 길이 없다. -- 템플릿의 `IntegrationEventEncoderPort`(`JsonIntegrationEventEncoder`)는 여기가 아니라 - `adapter:outbound:support`에 있다: 유스케이스는 append하기 전에 인코딩하는데, 이 모듈을 싣지 않는 조립도 - 있다. R1 contract·binding 컴파일러와 JSON Schema envelope 인코더는 2026-09-25에 지웠다 - (`docs/capability-status.md`). -- 주 classpath에 JSON Schema 엔진(NetworkNT)이 없다. 증거 manifest schema 검사와 capability card 검사 - (`release/`)는 이 leaf의 시험(`evidence/`)이다. snakeyaml은 시험에서만 쓴다(소유자 결정 2026-09-25). -- 유스케이스 순서나 업무 라우팅 정책을 broker 어댑터 안에 숨기지 않는다. -- `OutboxMessagePublishAdapter`는 위임만 하고 의존성 로그를 내지 않는다. 확정된 FAILED/DEAD 전이가 정해진 - ERROR 하나를 가진다. - -## 테스트 - -가짜 정해진 publisher로 단위·계약 시험을 쓴다. 이 모듈만 보는 시험은 실제 네트워크나 broker를 쓰지 않는다. -설정이 바뀌면 settings record에 바인딩·검증 시험을 더한다. +@AGENTS.md diff --git a/src/adapter/outbound/messaging/README.md b/src/adapter/outbound/messaging/README.md index 95aa5803..3cce4894 100644 --- a/src/adapter/outbound/messaging/README.md +++ b/src/adapter/outbound/messaging/README.md @@ -5,7 +5,7 @@ adapter로 구조화한다. 허용/금지 의존 정책은 `src/config/architecture/modules.json`과 이 모듈의 -[CLAUDE.md](CLAUDE.md)가 소유한다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를 모아둔 +[AGENTS.md](AGENTS.md)가 소유한다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를 모아둔 참조용 기록이다. ## 모듈 개요 diff --git a/src/adapter/outbound/notification/AGENTS.md b/src/adapter/outbound/notification/AGENTS.md new file mode 100644 index 00000000..16bd153e --- /dev/null +++ b/src/adapter/outbound/notification/AGENTS.md @@ -0,0 +1,49 @@ +# adapter:outbound:notification — 알림 어댑터 + +## 등록 정보 + +- 모듈 ID: `adapter-outbound-notification` +- Gradle 경로: `:adapter:outbound:notification` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:notification:test --console=plain` +- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. +- registry 정본: `src/config/architecture/modules.json`. + +패키지 루트: `dev.caskeleton.adapter.outbound.notification`. + +## 책임 + +- 지금의 raw 알림 router·provider 이음매는 리뷰를 거친 정해진 전환(cutover)이 지울 때까지 `R0 legacy` 호환 + 기준선으로만 지킨다. +- 앞으로의 provider 프로토콜은 애플리케이션이 가진 포트 뒤에서 구현하고, SDK·전송·bootstrap·영속 타입을 + 새게 하지 않는다. +- provider 설정, 기술적 대체 장치, provider 연결을 가진다. 모드, 자격, 재시도·대체 판단, 업무 실패의 뜻은 + 애플리케이션 정책이 가진다. +- 공용 outbound 관심사는 `adapter:outbound:support`를 다시 쓴다. + +## 지금의 R0 동결 + +- `RoutingNotifier`가 `(Channel, providerId)` 위에서 route 목록으로 퍼뜨린다. +- `FailOpenNotificationProvider`가 전역 fail-open 규칙 하나를 적용한다. +- `google-email`/`GoogleEmailClient`와 `slack-webhook`/`SlackClient`는 fake로만 쓰는 확장 이음매다. 운영 연동이나 + 검증된 provider card가 아니다. +- 커밋해 둔 provider 선택 키는 router의 `routes` + provider `enabled` 문법과 어긋나 있다. 정해진 그래프가 + 대신할 때까지 그 어긋남을 지키고 적어 둔다. 옛 키를 소리 없이 다르게 해석하지 않는다. +- 기능·애플리케이션 운영 소비자가 없고, 실제 provider·durable·수신 확인·보안·부하·교체 증거가 없다. +- 지울 옛 코드의 정확한 목록은 [README.md](README.md)에 있다. 정해진 대체물을 만드는 동안 그 클래스에 동작을 + 더하지 않는다. + +## 경계 + +- 허용 의존 edge는 이 모듈의 `src/config/architecture/modules.json` 항목에서만 온다. +- inbound DTO·controller, 영속, bootstrap, 샘플 의존이 없다. +- provider 선택은 설정한 채널로 보낼 수 있지만 업무 자격 규칙을 담으면 안 된다. +- 줄 안에 완전한 이름으로 쓴 타입 참조가 없다. `adapter:outbound:fileserver`는 이미 이것을 금지했고 이 leaf는 + 아니었다. 그래서 같은 구문이 한 capability에서는 결함이고 다음 capability에서는 평범한 문체였다. 플랫폼 자동 + 구성에 그런 것이 스물두 개 쌓여 있었다. + `dev.caskeleton.application.notification.platform.dispatch.ReconciliationJobStorePort jobs`처럼 쓴 매개변수는 + import 블록이 읽기 쉽게 보여 주려고 있는 바로 그 leaf 사이 edge를 import 블록에서 숨긴다. + +## 테스트 + +provider·client fake와 계약 시험을 쓴다. 실제 webhook이나 email 네트워크 호출이 없다. 설정을 바꾸면 +바인딩·검증 시험을 더한다. diff --git a/src/adapter/outbound/notification/CLAUDE.md b/src/adapter/outbound/notification/CLAUDE.md index 16bd153e..43c994c2 100644 --- a/src/adapter/outbound/notification/CLAUDE.md +++ b/src/adapter/outbound/notification/CLAUDE.md @@ -1,49 +1 @@ -# adapter:outbound:notification — 알림 어댑터 - -## 등록 정보 - -- 모듈 ID: `adapter-outbound-notification` -- Gradle 경로: `:adapter:outbound:notification` -- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:notification:test --console=plain` -- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. -- registry 정본: `src/config/architecture/modules.json`. - -패키지 루트: `dev.caskeleton.adapter.outbound.notification`. - -## 책임 - -- 지금의 raw 알림 router·provider 이음매는 리뷰를 거친 정해진 전환(cutover)이 지울 때까지 `R0 legacy` 호환 - 기준선으로만 지킨다. -- 앞으로의 provider 프로토콜은 애플리케이션이 가진 포트 뒤에서 구현하고, SDK·전송·bootstrap·영속 타입을 - 새게 하지 않는다. -- provider 설정, 기술적 대체 장치, provider 연결을 가진다. 모드, 자격, 재시도·대체 판단, 업무 실패의 뜻은 - 애플리케이션 정책이 가진다. -- 공용 outbound 관심사는 `adapter:outbound:support`를 다시 쓴다. - -## 지금의 R0 동결 - -- `RoutingNotifier`가 `(Channel, providerId)` 위에서 route 목록으로 퍼뜨린다. -- `FailOpenNotificationProvider`가 전역 fail-open 규칙 하나를 적용한다. -- `google-email`/`GoogleEmailClient`와 `slack-webhook`/`SlackClient`는 fake로만 쓰는 확장 이음매다. 운영 연동이나 - 검증된 provider card가 아니다. -- 커밋해 둔 provider 선택 키는 router의 `routes` + provider `enabled` 문법과 어긋나 있다. 정해진 그래프가 - 대신할 때까지 그 어긋남을 지키고 적어 둔다. 옛 키를 소리 없이 다르게 해석하지 않는다. -- 기능·애플리케이션 운영 소비자가 없고, 실제 provider·durable·수신 확인·보안·부하·교체 증거가 없다. -- 지울 옛 코드의 정확한 목록은 [README.md](README.md)에 있다. 정해진 대체물을 만드는 동안 그 클래스에 동작을 - 더하지 않는다. - -## 경계 - -- 허용 의존 edge는 이 모듈의 `src/config/architecture/modules.json` 항목에서만 온다. -- inbound DTO·controller, 영속, bootstrap, 샘플 의존이 없다. -- provider 선택은 설정한 채널로 보낼 수 있지만 업무 자격 규칙을 담으면 안 된다. -- 줄 안에 완전한 이름으로 쓴 타입 참조가 없다. `adapter:outbound:fileserver`는 이미 이것을 금지했고 이 leaf는 - 아니었다. 그래서 같은 구문이 한 capability에서는 결함이고 다음 capability에서는 평범한 문체였다. 플랫폼 자동 - 구성에 그런 것이 스물두 개 쌓여 있었다. - `dev.caskeleton.application.notification.platform.dispatch.ReconciliationJobStorePort jobs`처럼 쓴 매개변수는 - import 블록이 읽기 쉽게 보여 주려고 있는 바로 그 leaf 사이 edge를 import 블록에서 숨긴다. - -## 테스트 - -provider·client fake와 계약 시험을 쓴다. 실제 webhook이나 email 네트워크 호출이 없다. 설정을 바꾸면 -바인딩·검증 시험을 더한다. +@AGENTS.md diff --git a/src/adapter/outbound/objectstorage/AGENTS.md b/src/adapter/outbound/objectstorage/AGENTS.md new file mode 100644 index 00000000..49182c7c --- /dev/null +++ b/src/adapter/outbound/objectstorage/AGENTS.md @@ -0,0 +1,48 @@ +# adapter:outbound:objectstorage — 모듈 규칙 + +## 등록 정보 + +- 모듈 ID: `adapter-outbound-objectstorage` +- Gradle 경로: `:adapter:outbound:objectstorage` +- 이 모듈만 시험: `./gradlew :adapter:outbound:objectstorage:test --console=plain` +- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. +- registry 정본: `src/config/architecture/modules.json`. + +패키지 루트: `dev.caskeleton.adapter.outbound.objectstorage`. 설계 근거와 사실대로 적은 준비 상태는 +[README.md](README.md)와 `docs/registries/object-storage-readiness.yaml`에 있다. + +## 책임 + +- application-core의 semantic object 게시·읽기·폐기·operation 해석 포트를 provider 중립의 한계 있는 streaming과 + 엄격한 durable 제어 레코드 뒤에서 구현한다. +- 기본 꺼짐인 `app.object-storage` 설정을, 고른 자원을 만들기 전에 정확하고 바뀌지 않는 + provider·destination·route·policy 바인딩으로 컴파일한다. +- R1 전용 개발 provider로 `filesystem-local-dev`를 준다. +- scanner 유지보수 조립은 따로 둔다. 지원하지 않는 capability는 bean을 기여하지 않는다. purge·direct-grant· + multipart 포트는 없다. + +## 허용 + +- 프로젝트 의존은 `src/config/architecture/modules.json`의 `adapter-outbound-objectstorage` 항목이 허용한 것뿐이다. + 지금은 application-core, shared-contract, application-objectstorage, 그리고 등록된 support edge + (`adapter:outbound:support`: 모든 local-dev 파일 접근이 거치는 descriptor 기반 `SecureFileAccess`/ + `SecureDirectoryWalk`, 그리고 `StrictSettingsBinder` — `app.object-storage` 트리는 환경 변수까지 엄격하게 + 바인딩한다. capability 규칙 4)다. +- provider SDK·설정 타입은 이 leaf 안에 머문다. +- provider 기여는 부작용 없이 지원 내용을 설명할 수 있고, 정확히 골라진 뒤에만 자원을 만들 수 있다. + +## 금지 + +- inbound 어댑터, 이웃 outbound 어댑터, 영속, app-bootstrap 의존. +- provider 키·경로·locator·SDK 타입·Spring 타입·제어 레코드 타입이 application-core로 새는 것. +- 기본 provider·destination·namespace, 운영에서 local-dev, capability가 꺼져 있을 때 기동 중 변경. +- 보통 라우팅 타입이 scanner 유지보수 포트를 구현하기. +- `docs/registries/object-storage-readiness.yaml`의 정확한 행보다 높은 주장. +- 새 semantic operation을 옛 호출자 키 기반 덮어쓰기 뜻으로 되돌려 맞추기. + +## 테스트 + +```bash +cd src +./gradlew :adapter:outbound:objectstorage:check --console=plain +``` diff --git a/src/adapter/outbound/objectstorage/CLAUDE.md b/src/adapter/outbound/objectstorage/CLAUDE.md index 49182c7c..43c994c2 100644 --- a/src/adapter/outbound/objectstorage/CLAUDE.md +++ b/src/adapter/outbound/objectstorage/CLAUDE.md @@ -1,48 +1 @@ -# adapter:outbound:objectstorage — 모듈 규칙 - -## 등록 정보 - -- 모듈 ID: `adapter-outbound-objectstorage` -- Gradle 경로: `:adapter:outbound:objectstorage` -- 이 모듈만 시험: `./gradlew :adapter:outbound:objectstorage:test --console=plain` -- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. -- registry 정본: `src/config/architecture/modules.json`. - -패키지 루트: `dev.caskeleton.adapter.outbound.objectstorage`. 설계 근거와 사실대로 적은 준비 상태는 -[README.md](README.md)와 `docs/registries/object-storage-readiness.yaml`에 있다. - -## 책임 - -- application-core의 semantic object 게시·읽기·폐기·operation 해석 포트를 provider 중립의 한계 있는 streaming과 - 엄격한 durable 제어 레코드 뒤에서 구현한다. -- 기본 꺼짐인 `app.object-storage` 설정을, 고른 자원을 만들기 전에 정확하고 바뀌지 않는 - provider·destination·route·policy 바인딩으로 컴파일한다. -- R1 전용 개발 provider로 `filesystem-local-dev`를 준다. -- scanner 유지보수 조립은 따로 둔다. 지원하지 않는 capability는 bean을 기여하지 않는다. purge·direct-grant· - multipart 포트는 없다. - -## 허용 - -- 프로젝트 의존은 `src/config/architecture/modules.json`의 `adapter-outbound-objectstorage` 항목이 허용한 것뿐이다. - 지금은 application-core, shared-contract, application-objectstorage, 그리고 등록된 support edge - (`adapter:outbound:support`: 모든 local-dev 파일 접근이 거치는 descriptor 기반 `SecureFileAccess`/ - `SecureDirectoryWalk`, 그리고 `StrictSettingsBinder` — `app.object-storage` 트리는 환경 변수까지 엄격하게 - 바인딩한다. capability 규칙 4)다. -- provider SDK·설정 타입은 이 leaf 안에 머문다. -- provider 기여는 부작용 없이 지원 내용을 설명할 수 있고, 정확히 골라진 뒤에만 자원을 만들 수 있다. - -## 금지 - -- inbound 어댑터, 이웃 outbound 어댑터, 영속, app-bootstrap 의존. -- provider 키·경로·locator·SDK 타입·Spring 타입·제어 레코드 타입이 application-core로 새는 것. -- 기본 provider·destination·namespace, 운영에서 local-dev, capability가 꺼져 있을 때 기동 중 변경. -- 보통 라우팅 타입이 scanner 유지보수 포트를 구현하기. -- `docs/registries/object-storage-readiness.yaml`의 정확한 행보다 높은 주장. -- 새 semantic operation을 옛 호출자 키 기반 덮어쓰기 뜻으로 되돌려 맞추기. - -## 테스트 - -```bash -cd src -./gradlew :adapter:outbound:objectstorage:check --console=plain -``` +@AGENTS.md diff --git a/src/adapter/outbound/objectstorage/README.md b/src/adapter/outbound/objectstorage/README.md index 696b97c3..89d51fed 100644 --- a/src/adapter/outbound/objectstorage/README.md +++ b/src/adapter/outbound/objectstorage/README.md @@ -4,7 +4,7 @@ `dev.caskeleton.application.objectstorage`의 semantic 계약을 구현하고, provider 키·경로·SDK 타입·제어 레코드를 애플리케이션 경계 뒤에 둔다. -허용 운영 의존은 `src/config/architecture/modules.json`이 가진다. 모듈 규칙은 [CLAUDE.md](CLAUDE.md), 전체 +허용 운영 의존은 `src/config/architecture/modules.json`이 가진다. 모듈 규칙은 [AGENTS.md](AGENTS.md), 전체 설계는 `docs/design/2026-07-28-objectstorage-production-capability-design.md`, 정확한 증거 주장은 `docs/registries/object-storage-readiness.yaml`에 있다. diff --git a/src/adapter/outbound/persistence-fileserver/AGENTS.md b/src/adapter/outbound/persistence-fileserver/AGENTS.md new file mode 100644 index 00000000..94273307 --- /dev/null +++ b/src/adapter/outbound/persistence-fileserver/AGENTS.md @@ -0,0 +1,59 @@ +# persistence-fileserver + +파일 서버 capability의 관계형 영속이다: 엔티티, Spring Data repository, `application-fileserver` 포트를 구현하는 +store 어댑터. 루트 `AGENTS.md`와 `adapter/outbound/persistence-jpa/AGENTS.md`도 그대로 적용된다. 이 파일은 이 +leaf에만 있는 것을 더한다. + +## 패키지 + +- `entity/` — JPA 행만. 모든 엔티티는 `AssignedIdEntity`를 상속한다. +- `repository/` — Spring Data 인터페이스와 그것이 돌리는 SQL 글(`CleanupClaimSql`). +- 패키지 루트 — store 어댑터(`Jpa*`), `FileEntityMapper`, 그것들을 bean으로 등록하는 `@Configuration` + 클래스. + +`persistence-notification`도 같은 규칙(`platform.entity`, `platform.repository`, 어댑터는 `platform`)을 +따르므로 두 capability leaf를 같은 방식으로 읽는다. + +## 규칙 + +- **트랜잭션.** store는 트랜잭션을 열지 않는다. 모든 쓰기는 `CallerTransaction.require(" ")`로 + 시작한다. 그래서 `TransactionPort.inWrite`를 잊은 유스케이스는 문장마다 커밋하지 않고 실패한다. +- **새 행.** id를 insert 전에 정하므로 엔티티가 새것인지 스스로 말해야 한다: `AssignedIdEntity` + (`Persistable`)를 상속한다. 그렇지 않으면 `save`가 merge한다 — insert마다 SELECT가 앞서고, 이미 있는 id로 + 하는 두 번째 insert가 primary key에서 실패하지 않고 행을 덮어쓴다. 새 `@Version` 열은 primitive `long`으로 둬도 + 된다. 새것인지는 version이 아니라 `Persistable`이 정한다. +- **여기에 정책을 두지 않는다.** 재시도 예산, lease 길이 같은 판단은 `application-fileserver`의 것이고 포트 + 인자로 온다. claim token 같은 fence는 어댑터 필드가 아니라 포트 타입(`CleanupItem.claimToken`)에 실려 다닌다. +- **claim.** queue claim은 문장 하나다: CTE + `FOR UPDATE SKIP LOCKED` + `RETURNING`(`CleanupClaimSql`). 마무리 + 처리는 claim token을 맞춰 보고, 낡은 worker이면 0행을 update한다. + +## migration + +- `src/main/resources/db/migration/jpa/fileserver/V*.sql`. capability 자신의 Flyway stream + (`flyway_jpa_fileserver_history`)으로 적용한다. +- 적용한 파일은 고치지 않는다. 새 버전과 그 hash를 불변 목록에 더한다. `persistence-jpa`의 + `AppliedMigrationImmutabilityTest`가 이 파일들을 있는 자리에서 고정한다. + +## 테스트 + +- `src/test` — container 없는 이 leaf 자신의 시험. 돌리기: + `./gradlew :adapter:outbound:persistence-fileserver:test --console=plain`. + - `FileserverStoreCallerTransactionTest` — 모든 store의 보호된 쓰기는 호출자 트랜잭션이 없으면 repository에 + 닿기 전에 거절한다(위 트랜잭션 규칙, 쓰기마다 경우 하나. Spring Data repository는 mock이다). + - `FileserverPersistenceActivationTest` — scan은 `app.fileserver-platform.enabled` 뒤에서 이 패키지만 덮고, + JPA 루트 자동 구성보다 먼저 돈다. + - `repository.CleanupClaimSqlTest` — claim 글이 문장 하나 모양을 지킨다(claim 규칙). 잠금 자체는 + `PostgreSqlFileserverReclamationIntegrationTest`가 PostgreSQL에서 본다. + - `entity.AssignedIdEntityTest` — H2 위의 Hibernate에서 `Persistable`로 새것인지 정한다. + 새 store 쓰기는 보호 시험에 자기 경우를 더한다. 새 자동 구성은 켜기 시험에 자기 줄을 더한다. +- 포트 계약은 `application-fileserver` testFixtures에 있다(`*PortContract`, 그리고 테이블 하나를 같이 쓰는 quota + 포트 셋의 `FileQuotaLedgerContract`). 메모리 fake와 PostgreSQL 시험이 모두 그것을 상속한다. 이 leaf가 구현하는 + 포트는 모두 계약이 있다(`docs/testing/TESTING_STRATEGY.md` 9.3절). 2026-11-03에 더한 일곱 개의 PostgreSQL + 쪽은 `jpa-contract` tag를 달고 persistence-jpa의 `jpaPlatformContractTest` lane에서 + `FileserverPostgreSqlStack` 위에 돈다. 경우마다 그 시계를 옮긴다. +- 실제 PostgreSQL 시험은 아직 `persistence-jpa`의 `postgresqlIntegrationTest` source set에 있다. 그 source set이 + container와 Flyway 배선을 가지고, JPA readiness card(`persistence-jpa/release/readiness-cards.yaml`, + `JpaReadinessRegistryTest`가 검사)가 그 시험을 그 leaf의 태스크로 이름 댄다 — 옮기려면 card의 태스크와 + selector도 함께 옮겨야 한다: `postgresqlFileserverMigrationIntegrationTest`, + `postgresqlFileserverMetadataIntegrationTest`, `postgresqlFileserverReclamationIntegrationTest` + (`./gradlew :adapter:outbound:persistence-jpa: --console=plain`). diff --git a/src/adapter/outbound/persistence-fileserver/CLAUDE.md b/src/adapter/outbound/persistence-fileserver/CLAUDE.md index bb4c0a83..43c994c2 100644 --- a/src/adapter/outbound/persistence-fileserver/CLAUDE.md +++ b/src/adapter/outbound/persistence-fileserver/CLAUDE.md @@ -1,59 +1 @@ -# persistence-fileserver - -파일 서버 capability의 관계형 영속이다: 엔티티, Spring Data repository, `application-fileserver` 포트를 구현하는 -store 어댑터. 루트 `AGENTS.md`와 `adapter/outbound/persistence-jpa/CLAUDE.md`도 그대로 적용된다. 이 파일은 이 -leaf에만 있는 것을 더한다. - -## 패키지 - -- `entity/` — JPA 행만. 모든 엔티티는 `AssignedIdEntity`를 상속한다. -- `repository/` — Spring Data 인터페이스와 그것이 돌리는 SQL 글(`CleanupClaimSql`). -- 패키지 루트 — store 어댑터(`Jpa*`), `FileEntityMapper`, 그것들을 bean으로 등록하는 `@Configuration` - 클래스. - -`persistence-notification`도 같은 규칙(`platform.entity`, `platform.repository`, 어댑터는 `platform`)을 -따르므로 두 capability leaf를 같은 방식으로 읽는다. - -## 규칙 - -- **트랜잭션.** store는 트랜잭션을 열지 않는다. 모든 쓰기는 `CallerTransaction.require(" ")`로 - 시작한다. 그래서 `TransactionPort.inWrite`를 잊은 유스케이스는 문장마다 커밋하지 않고 실패한다. -- **새 행.** id를 insert 전에 정하므로 엔티티가 새것인지 스스로 말해야 한다: `AssignedIdEntity` - (`Persistable`)를 상속한다. 그렇지 않으면 `save`가 merge한다 — insert마다 SELECT가 앞서고, 이미 있는 id로 - 하는 두 번째 insert가 primary key에서 실패하지 않고 행을 덮어쓴다. 새 `@Version` 열은 primitive `long`으로 둬도 - 된다. 새것인지는 version이 아니라 `Persistable`이 정한다. -- **여기에 정책을 두지 않는다.** 재시도 예산, lease 길이 같은 판단은 `application-fileserver`의 것이고 포트 - 인자로 온다. claim token 같은 fence는 어댑터 필드가 아니라 포트 타입(`CleanupItem.claimToken`)에 실려 다닌다. -- **claim.** queue claim은 문장 하나다: CTE + `FOR UPDATE SKIP LOCKED` + `RETURNING`(`CleanupClaimSql`). 마무리 - 처리는 claim token을 맞춰 보고, 낡은 worker이면 0행을 update한다. - -## migration - -- `src/main/resources/db/migration/jpa/fileserver/V*.sql`. capability 자신의 Flyway stream - (`flyway_jpa_fileserver_history`)으로 적용한다. -- 적용한 파일은 고치지 않는다. 새 버전과 그 hash를 불변 목록에 더한다. `persistence-jpa`의 - `AppliedMigrationImmutabilityTest`가 이 파일들을 있는 자리에서 고정한다. - -## 테스트 - -- `src/test` — container 없는 이 leaf 자신의 시험. 돌리기: - `./gradlew :adapter:outbound:persistence-fileserver:test --console=plain`. - - `FileserverStoreCallerTransactionTest` — 모든 store의 보호된 쓰기는 호출자 트랜잭션이 없으면 repository에 - 닿기 전에 거절한다(위 트랜잭션 규칙, 쓰기마다 경우 하나. Spring Data repository는 mock이다). - - `FileserverPersistenceActivationTest` — scan은 `app.fileserver-platform.enabled` 뒤에서 이 패키지만 덮고, - JPA 루트 자동 구성보다 먼저 돈다. - - `repository.CleanupClaimSqlTest` — claim 글이 문장 하나 모양을 지킨다(claim 규칙). 잠금 자체는 - `PostgreSqlFileserverReclamationIntegrationTest`가 PostgreSQL에서 본다. - - `entity.AssignedIdEntityTest` — H2 위의 Hibernate에서 `Persistable`로 새것인지 정한다. - 새 store 쓰기는 보호 시험에 자기 경우를 더한다. 새 자동 구성은 켜기 시험에 자기 줄을 더한다. -- 포트 계약은 `application-fileserver` testFixtures에 있다(`*PortContract`, 그리고 테이블 하나를 같이 쓰는 quota - 포트 셋의 `FileQuotaLedgerContract`). 메모리 fake와 PostgreSQL 시험이 모두 그것을 상속한다. 이 leaf가 구현하는 - 포트는 모두 계약이 있다(`docs/testing/TESTING_STRATEGY.md` 9.3절). 2026-11-03에 더한 일곱 개의 PostgreSQL - 쪽은 `jpa-contract` tag를 달고 persistence-jpa의 `jpaPlatformContractTest` lane에서 - `FileserverPostgreSqlStack` 위에 돈다. 경우마다 그 시계를 옮긴다. -- 실제 PostgreSQL 시험은 아직 `persistence-jpa`의 `postgresqlIntegrationTest` source set에 있다. 그 source set이 - container와 Flyway 배선을 가지고, JPA readiness card(`persistence-jpa/release/readiness-cards.yaml`, - `JpaReadinessRegistryTest`가 검사)가 그 시험을 그 leaf의 태스크로 이름 댄다 — 옮기려면 card의 태스크와 - selector도 함께 옮겨야 한다: `postgresqlFileserverMigrationIntegrationTest`, - `postgresqlFileserverMetadataIntegrationTest`, `postgresqlFileserverReclamationIntegrationTest` - (`./gradlew :adapter:outbound:persistence-jpa: --console=plain`). +@AGENTS.md diff --git a/src/adapter/outbound/persistence-jpa/AGENTS.md b/src/adapter/outbound/persistence-jpa/AGENTS.md new file mode 100644 index 00000000..b6131bef --- /dev/null +++ b/src/adapter/outbound/persistence-jpa/AGENTS.md @@ -0,0 +1,357 @@ +# adapter:outbound:persistence-jpa — JPA·PostgreSQL 영속 어댑터 + +## 등록 정보 + +- 모듈 ID: `adapter-outbound-persistence-jpa` +- Gradle 경로: `:adapter:outbound:persistence-jpa` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:persistence-jpa:test --console=plain` +- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. +- registry 정본: `src/config/architecture/modules.json`. + +패키지 루트: `dev.caskeleton.adapter.outbound.persistence`. + +예전에 코드 주석으로 두던 설계 결정(트랜잭션 template, 감사 값 잡기, 실패 번역 SPI, 멱등성·outbox 동시성, 분산 +lock TTL)은 [README.md](README.md)에 있다. 이 파일은 모듈 규칙과 계약 표의 정본으로 남는다. + +이 모듈은 RDBMS·JPA 구현 기반이다. MongoDB, Redis, DynamoDB나 다른 NoSQL 저장소를 위한 저장소 중립 core가 아니다. +앞으로의 NoSQL 영속 어댑터는 application·domain 포트를 직접 구현하고 이 모듈에 의존하면 안 된다. + +## JPA 관계형 영속 플랫폼 + +`docs/design/2026-08-11-jpa-persistence-platform-design.md`의 플랫폼을 여기 구현했다. 설계는 그것을 Stable 라이브러리 +모듈 18개로 모델링한다. 이 저장소의 실패하면 닫히는 registry가 그 배치보다 앞서므로, 그 모듈들은 이 leaf의 +**패키지**이고 `docs/jpa/repository-adaptation.md`가 그 대응을 적는다. 타입을 다른 패키지로 옮기기 전에 그것을 읽는다. + +| 플랫폼 패키지 | 가지는 것 | +|---|---| +| `autoconfigure` | package-private Boot 조립 루트·런타임: vendor와 선택 저장소 import, provider runtime bean. 일부러 공개 API로 내놓지 않는다 | +| `api` (+ `.capability`, `.error`, `.query`, `.transaction`) | 프레임워크 없는 계약: operation·query 이름, 안정된 오류 계층, 커밋 완료 증거, keyset cursor | +| `transaction` | `SpringTransaction`, 유일한 트랜잭션 엔진(Spring `PlatformTransactionManager` 위의 `TransactionPort`) | +| `springdata` | repository fragment, 안전한 정렬, fetch plan, keyset 실행, stream guard | +| `hibernate` (+ `.batch`, `.bulk`, `.stateless`) | statement inspector, 통계, batch, bulk DML, stateless session | +| `postgresql` (+ `.error`, `.lock`, `.constraint`, `.json`, `.array`, `.range`, `.copy`) | SQLSTATE 분류, lock 옵션, JSONB, 배열과 범위, COPY | +| `migration` | `FlywaySchemaPolicy`(`startup` 패키지의 위험 설정 guard가 조립한다) | +| `startup` | package-private 기동 정책(`JpaStartupAutoConfiguration`): Flyway migration 전략, datasource env·제품 검사, OSIV·DDL·Hikari·TLS·H2 guard, `jpaplatform` actuator view, readiness `db` 기여. app-bootstrap에서 여기로 옮겼다 | +| `cache`, `envers`, `querydsl`, `security`, `observation` | 골라 쓰는 라이브러리 capability와 runtime role 검증기 | +| `experimental` | multi-tenancy, RLS, schema·database 테넌시, read replica — 배포가 스스로 만드는 라이브러리 코드. 켜는 flag가 없다 | +| `testkit`(`src/testFixtures/java`) | ArchUnit 규칙, fixture, query·plan 단언, PostgreSQL 표, 장애 주입, Flyway validate gate, concurrent index inspector, lock-wait inspector | + +`springdata`, `hibernate`(`.batch`, `.bulk`, `.stateless`, statement inspector), `postgresql`(`.error`, `.lock`, +`.constraint`, `.json`, `.array`, `.range`, `.copy`), `api.query`, `envers`, `querydsl`, `cache`, `observation`, +`experimental`은 **라이브러리 API**다: 어떤 설정도 그것을 조립하지 않고, 서비스가 이 leaf를 `implementation`으로 받는 +자기 어댑터 leaf에서 부른다. 진입점과 각각을 증명하는 시험은 [README.md](README.md) 「라이브러리 API」에 있다. + +### Spring 조립 소유 + +`META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports`는 package-private 항목 둘을 내놓는다: +`PersistenceJpaAutoConfiguration`과 `PersistenceJpaRuntimeConfig`. Boot가 그 후보를 따로따로 읽으므로 **둘 다** +`app.persistence-jpa.enabled=true`를 요구한다. 첫째는 vendor·entity·repository와 capability 저장소 import를 가진다. +둘째는 provider runtime bean(`HibernateProviderPolicy`, `PostgreSqlRuntimeRoleVerifier`)만 기여한다. 트랜잭션 엔진은 +`SpringTransaction` 하나뿐이다. 두 번째 엔진(`SpringJpaTransactionExecutor`/`FullTransactionRetryCoordinator`)은 +2026-09-25에 지웠다 — `docs/capability-status.md`를 본다. 첫째 후보의 조건이 이웃 import 후보를 막아 준다고 기대지 +않는다. + +`enabled=false`는 bean만이 아니라 완전히 끄기다: `JpaActivationEnvironmentPostProcessor`(이 leaf의 `spring.factories`)가 +Boot의 `jdbc`/`hibernate`/`data.jpa`/`flyway` 자동 구성을 `spring.autoconfigure.exclude`에 붙인다. 그래서 DataSource, +pool, EntityManagerFactory, Flyway가 하나도 없다. + +소유자를 안전하게 지키는 PostgreSQL 멱등성도 같은 분할을 쓴다: 이 leaf는 `IdempotencyStorePort` 뒤의 실제 PostgreSQL +store를 만들고(`PostgreSqlIdempotencyStoreConfig`, `app.capabilities.idempotency.provider=postgresql`일 때만 켜진다), +`composition:idempotency`가 provider 고르기, TTL·lease·codec 정책, executor 만들기, 배타성 검증을 가진다. 그 provider를 +고르면 leaf는 `db/migration/jpa/core` + `db/migration/jpa/idempotency` Flyway stream도 적용하고 기동 때 capability +registry 행을 켜며(`IdempotencySchemaStream`, `app.runtime.migration-on-startup=false`이면 건너뛴다), PostgreSQL이 아닌 +data source를 거절하고, `IdempotencyReaper`를 돌린다. V1·JDBC 멱등성 store도 `jdbc` provider 값도 없다. + +이 모듈은 빌드 한 줄(`runtimeOnly project(':adapter:outbound:persistence-jpa')`)로 고르는 capability다. 템플릿의 기본 +조립은 이것을 싣지 않는다. 그래서 관계형 저장소가 있을 때만 뜻이 있는 것은 모두 여기 있고 모듈과 함께 켜진다: +migration 기동 순서, 해석된 datasource·버전 검증, OSIV·DDL·pool·TLS·vendor 안전, 걸러 낸 관리 endpoint·보고 +(`startup`), metric을 단 다중 인스턴스 lock(`lock`), readiness `db` 기여, 출하하는 설정 +(`config/module-defaults/persistence-jpa.yml`). 유스케이스 조립은 아니다: driven 어댑터가 유스케이스를 만들거나 부르면 +안 되므로 outbox relay는 `composition:outbox-relay`다. leaf에는 `dev.caskeleton.bootstrap` import가 하나도 없어야 한다. +기동 실패는 `adapter:outbound:support`(`support.startup`)를 거치고, 새 조립 도우미는 package-private로 둬서 배선 +실수로 `verifyJpaApiSurface`가 늘지 않게 한다. + +### 양보할 수 없는 것 + +- `GenericRepository`도 플랫폼 기반 repository도 없다. 도메인이 자기 repository를 가진다. +- `TransactionCompletionUnknownException`은 절대 재시도하지 않는다. `JpaFailureContext`는 재시도할 수 있는 + completion-unknown 실패를 나타내기를 거절하고, `SpringTransaction`은 아무것도 재시도하지 않는다. +- 재시도하는 호출자는 새 트랜잭션과 새 Persistence Context에서 유스케이스 전체를 다시 돌린다. +- OSIV는 모든 runtime profile에서 false다. schema 변경은 Flyway가 가지고 Hibernate는 검증만 한다. +- 이미 쓰이는 테이블을 잠그는 migration은 `SET LOCAL lock_timeout = '5s';`로 시작한다 + (`docs/jpa/migration-guide.md` "Bound the lock wait"). `MigrationLockWaitTest`가 그것이 없는 migration을 거절한다. 그 + 규칙 전에 릴리스한 migration 목록에는 새 migration을 넣지 않는다. 그 목록은 inspector가 문장을 새로 배우고 이미 + `main`에 있는 파일에서 그것을 찾았을 때만 늘어난다. +- Flyway는 PostgreSQL migration lock을 열린 트랜잭션이 아니라 세션 동안 쥔다. 아니면 `CREATE INDEX CONCURRENTLY` + migration이 Flyway를 영원히 기다린다: 모듈 기본값의 `spring.flyway.postgresql.transactional-lock: false`, 그리고 코드에서 + 만드는 모든 Flyway는 `FlywaySchemaPolicy.configure()`에서 시작한다(`JpaProductionArchitectureTest`가 + `Flyway.configure()`와 Flyway 설정을 직접 만드는 것 — `new FluentConfiguration()`, `new ClassicConfiguration()`, 하위 + 클래스 — 을 거절한다. `docs/jpa/migration-guide.md` "Who may change the schema"). +- metric tag, 예외 메시지, 로그는 SQL 매개변수, entity id, tenant id, 개인정보를 싣지 않는다. +- 계약은 실제 PostgreSQL에 대고 돈다. H2는 어떤 계약도 만족시키지 않는다. + +### 플랫폼 lane + +```bash +cd src +./gradlew :adapter:outbound:persistence-jpa:test # hermetic unit lane +./gradlew :adapter:outbound:persistence-jpa:jpaPlatformContractTest # real PostgreSQL +./gradlew :adapter:outbound:persistence-jpa:jpaPlatformMigrationTest # Flyway upgrade scenarios +./gradlew :adapter:outbound:persistence-jpa:jpaPlatformFailureTest # deadlock +./gradlew :adapter:outbound:persistence-jpa:jpaPlatformQueryPlanTest # EXPLAIN structure +./gradlew :adapter:outbound:persistence-jpa:jpaPlatformSecurityTest # runtime role privileges +./gradlew :adapter:outbound:persistence-jpa:jpaPlatformPoolContractTest # pool behaviour +# Release blocking composition is CI-owned; locally run the exact database qualification set: +./gradlew :adapter:outbound:persistence-jpa:jpaPlatformContractTest \ + :adapter:outbound:persistence-jpa:jpaPlatformMigrationTest \ + :adapter:outbound:persistence-jpa:jpaPlatformFailureTest \ + :adapter:outbound:persistence-jpa:jpaPlatformQueryPlanTest \ + :adapter:outbound:persistence-jpa:jpaPlatformSecurityTest \ + :adapter:outbound:persistence-jpa:jpaPlatformPoolContractTest +``` + +Docker를 쓰는 모든 lane은 실패하면 닫힌다. 고른 lane이 아무것도 찾지 못하거나 container가 시작하지 못하면 건너뛰기가 +아니라 오류다 — 건너뛴 계약은 아무도 시험하지 않은 데이터베이스에 대해 성공을 알린다. + +## 책임 + +- JPA 엔티티. +- Spring Data repository. +- 영속 mapper. +- repository 어댑터 구현. +- outbox append: 모델 하나. `JpaOutboxStore`가 `OutboxAppendPort`를 구현하고 `ValidatedIntegrationEvent`의 정확한 envelope + 바이트와 hash를 저장한다. claim은 그것으로 같은 이벤트를 되살린다. 정해진 metadata가 다 갖춰지지 않은 행은 읽을 수 + 없고 DEAD로 간다. 짐작으로 발행하지 않는다. `V19`는 발행하지 않은 정해진 형식 이전 행을 거절한다. +- outbox relay fencing: `claimBatch`가 claim의 행 lock 아래에서 claim한 relay(`lease_owner`)를 기록하고 + `lease_token`을 올린다(`V17`). `markPublished`/`markFailed`/`markDead`는 `event_id` + `IN_FLIGHT` + owner + token에 + 대한 조건부 UPDATE 하나이고 `APPLIED`/`STALE`을 돌려준다. 완료는 행을 읽어서 덮어쓰지 않는다. V2 outbox 세대는 + 2026-09-25에 지웠다(`docs/capability-status.md`). +- `TransactionPort` 구현(`SpringTransaction`) — 애플리케이션의 트랜잭션 의도와 Spring `PlatformTransactionManager` 사이의 + 다리. +- 감사 metadata 기반 + actor 이음매(`audit/AuditableEntity`, `audit/AuditContextPort`, `audit/DomainContextAuditContext`) — + 아래 「영속 감사 계약」을 본다. +- 모든 RDBMS vendor가 같이 쓰는 vendor SPI 확장점: + - `outbox/jpa/OutboxClaimRepository` — vendor 모듈이 claim 전략(예: FOR UPDATE SKIP LOCKED)을 구현한다. 구현은 그 + 옆 `outbox/postgresql`과 `outbox/h2`에 있다. + - `failure/SqlStateErrorMapping` — vendor 모듈이 vendor 전용 SQLState 행을 기여한다. + +## vendor 고르기 + +vendor 조립 둘이 이 모듈에 있고, 각각 자기 하위 패키지에 있으며, 각각 같은 SPI bean 둘(outbox claim, SQLState 대응)을 +등록한다: + +| vendor | 패키지 | 고르는 것 | schema 소유 | +| --- | --- | --- | --- | +| PostgreSQL | `.postgresql` | `app.persistence.vendor=postgresql`(기본값이기도 하다) | Flyway, `db/migration/postgresql` | +| H2 | `.h2` | `app.persistence.vendor=h2` | Hibernate `ddl-auto`, 엔티티만 | + +outbox와 멱등성 기능은 기능별, 그다음 vendor별로 조각을 모아 둔다: `outbox/{jpa,postgresql,h2}`와 +`idempotency/{jpa,postgresql}`. 어떤 claim repository를 등록할지는 여전히 위 vendor 설정이 정한다. 그 기능 클래스 중 +driver 타입을 import하는 것이 없으므로, 그것들이 `.postgresql` 밖에 있어도 +`PERSISTENCE_RDBMS_STAYS_VENDOR_NEUTRAL`이 계속 지켜진다. + +`config/PersistenceVendorSettings`가 선택자를 enum으로 바인딩한다. 그래서 모르는 값은 두 조립 중 어느 것도 읽지 않고 +`OutboxClaimRepository`가 없다는 오류로 나타나는 대신 기동 때 실패한다. 선택은 모듈이 정한다: 그 +`config/module-defaults/persistence-jpa.yml`이 모든 profile에서 vendor를 PostgreSQL로, `spring.flyway.enabled`를 +`APP_FLYWAY_ENABLED`(true)로 기본 설정한다. 조립 루트의 profile 파일은 더는 그것을 다시 적지 않는다(2026-11-01 +성숙도 리뷰 뒤로. 기본 조립 루트가 고르지 않은 capability의 설정을 알면 안 된다). H2는 `bootRunH2` 태스크가 +고르는, 개발자가 명시해서 빠지는 길이다. `PersistenceVendorProdSafetyValidator`(`startup`)는 어떤 +속성 출처가 주든 prod에서 H2를 거절한다. `bootRunH2`에서는 멱등성 provider가 `disabled`나 `redis`여야 한다: +`postgresql` provider는 기동 때 H2 data source를 거절한다. + +H2는 로컬 개발 저장소이지 두 번째 운영 대상이 아니다. migration 트리가 없으므로, migration에만 있는 테이블 — +capability schema registry, Spring Integration lock 테이블 — 은 H2에 없다. vendor 동시성과 migration 충실도는 +`postgresqlIntegrationTest`에 남는다. + +outbox claim은 H2가 돌리는 유일한 vendor 문장이고 내용이 같다 — H2 2.4.240은 `FOR UPDATE SKIP LOCKED`를 받고 잠긴 행을 +정말 건너뛰므로 claim이 뜻을 지킨다. `H2ClaimSqlTest`가 그것을 실제 H2에 대고 실행한다. H2에는 멱등성 store가 없다. + +### capability로 막은 store + +선택 capability 하나를 위한 어댑터는 이 모듈의 나머지와 달리 그 capability의 스위치를 단다. 지금은 `fileserver` +패키지가 그 경우다: 거기 있는 모든 `Jpa*` 어댑터는 +`@ConditionalOnProperty(prefix = "app.fileserver-platform", name = "enabled", havingValue = "true")`를 단다. + +그 막음이 없으면 이 모듈을 넣기만 한 조립 루트도 그 bean을 만들고, 각 bean에는 파일 서버 설정만 주는 협력 객체가 +필요하다. 지운 샘플 모듈이 쓰지도 않는 Fileserver 협력 객체 때문에 기동에 실패한 일이 그 예다. 아무도 켜지 않은 +capability의 store는 있으면 안 된다. + +## 허용 + +- `:application-core` +- `:domain-core` +- `:shared-contract` +- `:adapter:outbound:support`(타입 있는 기동 실패, EnvironmentPostProcessor 순서, readiness group, module-defaults 읽기) +- Spring Data JPA와 Spring transaction. + +## 금지 (Forbidden) + +- `adapter-web`, `app-bootstrap`, `adapter:outbound:support`를 뺀 다른 outbound 어댑터. +- 표현 계층 DTO. +- 업무 정책 판단. +- 영속 어댑터 안에 숨긴 유스케이스 조율. +- repository 어댑터가 애플리케이션 흐름을 감싸 `@Transactional`을 여는 것 — 포트를 가로지르는 트랜잭션은 애플리케이션 + 유스케이스가 `TransactionPort`로 가진다. 어댑터 안의 트랜잭션은 포트 메서드 자체가 원자적이어야 하는 저장 프로토콜을 + 정할 때만 허용한다(예: durable operation claim·읽기, live event 위치 할당 + insert). + [application-core/AGENTS.md](../../../application-core/AGENTS.md)를 본다. +- **DB driver**(`org.postgresql..`, `org.h2..`)나 **`org.flywaydb.database.postgresql..`** — vendor 전용이라 이 모듈의 + 맞는 vendor 패키지(`.postgresql`, `.h2`)에만 둔다. NoSQL 전용 의존은 앞으로 생길 자기 모듈에만 둔다. + `CleanArchitectureTest`의 ArchUnit `PERSISTENCE_RDBMS_STAYS_VENDOR_NEUTRAL`과 `PERSISTENCE_RDBMS_STAYS_NEUTRAL_OF_H2`가 + 강제한다. +- NoSQL 어댑터 코드. MongoDB·Redis·DynamoDB 어댑터는 이 모듈의 자식이 아니라 이웃 모듈이다. +- registry가 허용하지 않은 이웃 영속 어댑터나 inbound·outbound 어댑터. + +## TransactionPort 구현 계약 + +`SpringTransaction`은 모드마다 `TransactionTemplate`을 하나씩 미리 만든다: + +| 모드 | 전파 | 격리 | 읽기 전용 | timeout | +|---|---|---|---|---| +| `inWrite` | `REQUIRED` | `READ_COMMITTED`(pool) | `false` | `app.persistence-jpa.transaction.write-timeout`(30 s) | +| `inRootWrite` | `REQUIRED` | `READ_COMMITTED`(pool) | `false` | `inWrite`와 같음 | +| `inRead` | `REQUIRED` | `READ_COMMITTED`(pool) | `true` | `app.persistence-jpa.transaction.read-timeout`(30 s) | +| `inNew` | `REQUIRES_NEW` | `READ_COMMITTED`(pool) | `false` | 30 s, 고정 | + +격리 수준은 template이 아니라 pool에 고정한다: template은 `ISOLATION_DEFAULT`를 쓰고, 모듈 기본값이 +`spring.datasource.hikari.transaction-isolation: TRANSACTION_READ_COMMITTED`를 정하며(물리 연결마다 한 번 적용), +`HikariPoolConstraintValidator`가 다른 수준이면 기동을 거절한다. template마다 수준을 대면 Spring이 begin마다 +`getTransactionIsolation()`을 부르고, pgjdbc는 그것에 `SHOW TRANSACTION ISOLATION LEVEL` 왕복으로 답했다. + +모든 모드에는 시간 한계가 있다(2026-11-01부터). Spring이 남은 시간을 문장마다 넘기므로 느린 query나 lock 대기는 서버가 +취소하고(`57014` → `DB_QUERY_CANCELED`), 다음 문장 전에 기한이 지난 경우도 같은 코드를 받는다: JDBC 경로에서는 Spring의 +`TransactionTimedOutException`, JPA 경로(`JpaTransactionManager`, 운영)에서는 Hibernate 자신의 `TransactionException`이다. +후자는 SQLState가 없고, `SpringTransaction`이 기한이 지났음을 알기 때문에 분류된다(`translateAfterDeadline`). 기한 뒤에 +던진 업무 예외는 바꾸지 않고 넘긴다. + +미리 만든 template은 만든 뒤 바뀌지 않아서, 동시 호출자가 서로의 재설정을 볼 수 없다. `inRootWrite`는 미리 만든 쓰기 +template을 다시 쓰지만, 먼저 `TransactionSynchronizationManager.isActualTransactionActive()`를 검사한다. 실제 바깥 +트랜잭션이 있으면 action이나 `PlatformTransactionManager`를 부르기 전에 반드시 +`NestedRootTransactionRejectedException`을 던진다. `NEVER`나 `REQUIRES_NEW`를 쓰면 안 된다. + +`inRootWrite`는 `TransactionTemplate.execute`가 커밋한 뒤에만 action 값을 돌려준다. 커밋이 실패하면 트랜잭션 예외를 +올리고 호출자에게 성공 값을 돌려주지 않는다. + +### `inNew` 풀 크기 제약 (feature-application-port-usecase-contract) + +`REQUIRES_NEW`는 바깥 트랜잭션의 연결을 쥔 채 새 물리 JDBC 연결을 얻는다. pool은 다음을 만족하게 잡는다: + +``` +hikari.maximumPoolSize >= (concurrent_threads × (1 + max_inNew_depth)) + 1 +``` + +레코드마다 `inNew`를 부르는 반복문은 금지다(pool 고갈 + 교착 위험). 레코드를 `inNew` **하나** 안에서 묶어 처리하거나, +반복문을 트랜잭션 밖으로 뺀다. + +## 영속 실패 번역 계약 (feature-persistence-failure-baseline) + +날것의 Spring `DataAccessException`(과 그 안의 JPA 예외·SQLState·제약 이름)은 절대 표현 계층에 닿으면 안 된다. +`failure/PersistenceExceptionTranslator`가 `DataAccessException`을 SQLState로 아래 §SQLState → 오류 코드 표와 대조해 +분류하고, `DB_*` `OperationalError` 코드 하나를 실은 프레임워크 중립 `shared.error.PersistenceFailureException`을 돌려준다. + +**표준 행(core):** + +| SQLState | code | category | http | retryable | +|---|---|---|---|---| +| `08*` | `DB_UNAVAILABLE` | `TRANSIENT_DEPENDENCY` | 503 | true | +| `40001` | `DB_SERIALIZATION_FAILURE` | `CONFLICT` | 409 | true | +| `23502` | `DB_NULL_VIOLATION` | `DATA_INTEGRITY` | 409 | false | +| `23503` | `DB_FK_VIOLATION` | `DATA_INTEGRITY` | 409 | false | +| `23505` | `DB_UNIQUE_VIOLATION` | `CONFLICT` | 409 | false | +| `23514` | `DB_CHECK_VIOLATION` | `DATA_INTEGRITY` | 409 | false | + +**vendor 전용 행(vendor 모듈이 `SqlStateErrorMapping` SPI로 기여):** + +| SQLState | code | vendor | +|---|---|---| +| `40P01` | `DB_DEADLOCK` | PostgreSQL(`.postgresql` 패키지) | +| `55P03` | `DB_LOCK_TIMEOUT` | PostgreSQL | +| `25P03` | `DB_IDLE_IN_TX_TIMEOUT` | PostgreSQL | +| `57014` | `DB_QUERY_CANCELED` | PostgreSQL | +| `57P01`, `57P02` | `DB_UNAVAILABLE`(커밋 전. 커밋 중이면 completion-unknown) | PostgreSQL | +| `23513` | `DB_CHECK_VIOLATION` | H2(`.h2` 패키지) — H2는 CHECK를 core 표가 대응시키는 표준 23514가 아니라 23513으로 알린다 | +| `HYT00` | `DB_QUERY_CANCELED` | H2 — H2는 문장 timeout과 lock timeout을 상태 하나로 합친다 | + +PostgreSQL 행은 두 번째 표가 아니다: 2026-11-01 전에는 손으로 관리하던 두 번째 표가 이미 어긋나 있었다. +`PostgreSqlSqlStateErrorMapping`이 그 행을 `PostgreSqlFailureClassifier`(SQLState → `FailureCategory`)와 +`FailureCategory.operationalError()`(category → 코드)에서 끌어낸다 — 라이브러리 `PostgreSqlExceptionTranslator`가 쓰는 +것과 같은 분류다 — 그리고 위 표준 행, 전용 코드가 없는 category(`INTERNAL_ERROR`), `COMPLETION_UNKNOWN`(단계에 +따라 다르다)을 뺀다. PostgreSQL 상태를 더하려면 `PostgreSqlState`와 classifier에 더한다. 두 경로가 어떤 상태에서든 +다르면 `SqlStateClassificationParityTest`가 실패한다. + +**SQLState가 없고 타입으로 분류:** 진 `@Version` 경쟁(`OptimisticLockingFailureException`, JPA +`OptimisticLockException`) → `DB_OPTIMISTIC_CONFLICT`(409). 만료된 Spring 트랜잭션 기한(`TransactionTimedOutException`) +→ `DB_QUERY_CANCELED`. `SpringTransaction`이 시작한 트랜잭션의 기한이 지난 뒤의 다른 영속 실패(JPA, Spring +data-access, Spring transaction 예외) → `DB_QUERY_CANCELED`. + +**커밋 단계(`translateCommitFailure`, ADR-JPA-003):** action이 돌아왔고 `SpringTransaction`이 자기가 시작한 쓰기 +트랜잭션을 커밋하는 중이면, `08*`, `40003`, vendor가 기여한 종료 상태(`SqlStateErrorMapping.commitOutcomeUnknownStates()`: +PostgreSQL `57P01`, `57P02`), SQLState 없는 전송 끊김을 가진 실패는 `DB_UNAVAILABLE`이 아니라 +`TransactionCompletionUnknownException` → `DB_COMPLETION_UNKNOWN`(500, 절대 재시도하지 않음)이 된다: 서버가 이미 커밋했을 +수 있다. 서버가 분명히 거절한 커밋(예: 미뤄진 `23505`)은 위 자기 행을 지킨다. 읽기 전용 커밋은 `DB_UNAVAILABLE`을 지킨다. + +- `DataAccessException`을 잡는 repository 어댑터는 `translator.translate(ex)`를 부르고 carrier를 다시 던진다 + (`ifPresent(e -> { throw e; })`). 빈 결과는 모르는 SQLState라는 뜻이다 — 원래 예외를 다시 던져 web catch-all이 일반 + `INTERNAL` envelope으로 답하게 한다(새는 것 없음). +- category 정본은 값 10개의 `Category` enum이다 — `PERSISTENCE` category는 **없다**(설계 기록 §Audit CATEGORY_DRIFT). + +## 영속 감사 계약 (feature-persistence-auditing-contract) + +감사 metadata(`created_at` / `updated_at` / `created_by` / `updated_by`)는 기반 관심사이고 `domain-core`에 닿으면 안 된다. +`audit/AuditableEntity` `@MappedSuperclass`에만 있다. 도메인 aggregate의 영속 엔티티가 그것을 상속해서 고른다(생성 +명령이 만드는 서비스 persistence leaf의 엔티티가 그렇게 한다). 도메인 aggregate 자체는 감사 필드를 하나도 갖지 않는다. +ArchUnit `DOMAIN_IS_PURE`(`jakarta.persistence..` 없음)와 `DOMAIN_ENTITIES_DO_NOT_CARRY_AUDIT_FIELDS`(`..domain..` 아래에 +`createdAt`/`updatedAt`/`createdBy`/`updatedBy` 필드 없음)가 강제한다. + +- **잡기 = 손으로 명시해 넣기(지금 기본).** repository 어댑터가 생성자로 `Clock`과 `AuditContextPort`를 받고 `save`에서 + 감사 값을 넣는다: INSERT(version null) → `initializeAudit(now, actor)`. UPDATE(version 있음) → 저장된 `created_*`를 그대로 + 넘기고 + `applyModification(now, actor)`. `created_*`는 `updatable = false`다. +- **actor 이음매.** `AuditContextPort.currentActor()`는 runtime-context 전파 이음매를 읽고, principal이 묶여 있지 않으면 + (scheduler / Flyway / 익명) `"system"`으로 물러선다. actor 값의 뜻은 + feature-authentication-authorization-contract가 가진다(여기서는 UNSUPPORTED). 타입은 `String`으로 고정한다. +- **빠지는 것.** `IdempotencyRecordEntity`(자기 `created_at`, `updated_at` 없음) 같은 기반·불변 엔티티는 `AuditableEntity`를 + 상속하지 **않는다**. `version`·낙관적 lock은 이 감사 기반이 아니라 feature-persistence-failure-baseline / + feature-transaction-concurrency-contract가 가진다. +- **자랄 길(미룸).** 트리에 두 번째 감사 구현은 없다. 손으로 넣는 것이 실수가 너무 잦아지면, 정해진 `AuditableEntity` + 계약을 `created_*`/`updated_*` schema, actor 한계, `Clock`, `AuditContextPort` 뜻을 지키면서 한 번에 Spring Data + listener로 옮긴다. bulk·native `@Query` UPDATE도 listener를 지나지 않으므로 계속 감사 열을 명시해 넣어야 한다. + +## MapStruct 생성 mapper 예외 (feature-architecture-enforcement-rules) + +영속 mapper에 MapStruct를 들이면, 생성된 mapper 클래스에 `javax.annotation.processing.Generated`가 붙는다. mapper 경계 +위반을 금지하는 아키텍처 규칙은 반드시 ArchUnit predicate로 생성 코드를 뺀다: + +```java +import javax.annotation.processing.Generated; + +classes() + .that().resideInAPackage("..adapter.persistence.mapper..") + .and().areNotAnnotatedWith(Generated.class) + .should() /* ... boundary rule ... */; +``` + +> 애너테이션 FQN에 주의한다: MapStruct는 `javax.annotation.processing.Generated`를 쓴다. Spring AOT는 +> `org.springframework.aot.generate.Generated`를 쓴다 — 둘을 섞지 **않는다**. 예외는 반드시 빼려는 빌드 단계가 기대하는 +> 바로 그 애너테이션으로 범위를 잡는다. + +지금 ca-tmpl mapper는 손으로 쓴 것이라 ArchUnit에 MapStruct 예외를 아직 배선하지 않았다 — 생성을 더할 때 위 +predicate를 따르고, fixture mapper로 red/green 시험을 더한다. + +## NoSQL 확장 규칙 + +`adapter-persistence-nosql-core`를 미리 만들지 않는다. NoSQL 저장소는 모델과 운영 계약이 서로 다르다. 실제 MongoDB, +Redis, DynamoDB 어댑터가 필요해지면 이웃 모듈을 만든다: + +```text +adapter-persistence-mongodb +adapter-persistence-redis +adapter-persistence-dynamodb +``` + +그런 모듈은 application·domain 포트를 직접 구현하고 `adapter:outbound:persistence-jpa`에 의존하면 안 된다. + +## 테스트 + +```bash +cd src +./gradlew :adapter:outbound:persistence-jpa:test --console=plain +``` diff --git a/src/adapter/outbound/persistence-jpa/CLAUDE.md b/src/adapter/outbound/persistence-jpa/CLAUDE.md index 2fd3e384..43c994c2 100644 --- a/src/adapter/outbound/persistence-jpa/CLAUDE.md +++ b/src/adapter/outbound/persistence-jpa/CLAUDE.md @@ -1,357 +1 @@ -# adapter:outbound:persistence-jpa — JPA·PostgreSQL 영속 어댑터 - -## 등록 정보 - -- 모듈 ID: `adapter-outbound-persistence-jpa` -- Gradle 경로: `:adapter:outbound:persistence-jpa` -- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:persistence-jpa:test --console=plain` -- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. -- registry 정본: `src/config/architecture/modules.json`. - -패키지 루트: `dev.caskeleton.adapter.outbound.persistence`. - -예전에 코드 주석으로 두던 설계 결정(트랜잭션 template, 감사 값 잡기, 실패 번역 SPI, 멱등성·outbox 동시성, 분산 -lock TTL)은 [README.md](README.md)에 있다. 이 파일은 모듈 규칙과 계약 표의 정본으로 남는다. - -이 모듈은 RDBMS·JPA 구현 기반이다. MongoDB, Redis, DynamoDB나 다른 NoSQL 저장소를 위한 저장소 중립 core가 아니다. -앞으로의 NoSQL 영속 어댑터는 application·domain 포트를 직접 구현하고 이 모듈에 의존하면 안 된다. - -## JPA 관계형 영속 플랫폼 - -`docs/design/2026-08-11-jpa-persistence-platform-design.md`의 플랫폼을 여기 구현했다. 설계는 그것을 Stable 라이브러리 -모듈 18개로 모델링한다. 이 저장소의 실패하면 닫히는 registry가 그 배치보다 앞서므로, 그 모듈들은 이 leaf의 -**패키지**이고 `docs/jpa/repository-adaptation.md`가 그 대응을 적는다. 타입을 다른 패키지로 옮기기 전에 그것을 읽는다. - -| 플랫폼 패키지 | 가지는 것 | -|---|---| -| `autoconfigure` | package-private Boot 조립 루트·런타임: vendor와 선택 저장소 import, provider runtime bean. 일부러 공개 API로 내놓지 않는다 | -| `api` (+ `.capability`, `.error`, `.query`, `.transaction`) | 프레임워크 없는 계약: operation·query 이름, 안정된 오류 계층, 커밋 완료 증거, keyset cursor | -| `transaction` | `SpringTransaction`, 유일한 트랜잭션 엔진(Spring `PlatformTransactionManager` 위의 `TransactionPort`) | -| `springdata` | repository fragment, 안전한 정렬, fetch plan, keyset 실행, stream guard | -| `hibernate` (+ `.batch`, `.bulk`, `.stateless`) | statement inspector, 통계, batch, bulk DML, stateless session | -| `postgresql` (+ `.error`, `.lock`, `.constraint`, `.json`, `.array`, `.range`, `.copy`) | SQLSTATE 분류, lock 옵션, JSONB, 배열과 범위, COPY | -| `migration` | `FlywaySchemaPolicy`(`startup` 패키지의 위험 설정 guard가 조립한다) | -| `startup` | package-private 기동 정책(`JpaStartupAutoConfiguration`): Flyway migration 전략, datasource env·제품 검사, OSIV·DDL·Hikari·TLS·H2 guard, `jpaplatform` actuator view, readiness `db` 기여. app-bootstrap에서 여기로 옮겼다 | -| `cache`, `envers`, `querydsl`, `security`, `observation` | 골라 쓰는 라이브러리 capability와 runtime role 검증기 | -| `experimental` | multi-tenancy, RLS, schema·database 테넌시, read replica — 배포가 스스로 만드는 라이브러리 코드. 켜는 flag가 없다 | -| `testkit`(`src/testFixtures/java`) | ArchUnit 규칙, fixture, query·plan 단언, PostgreSQL 표, 장애 주입, Flyway validate gate, concurrent index inspector, lock-wait inspector | - -`springdata`, `hibernate`(`.batch`, `.bulk`, `.stateless`, statement inspector), `postgresql`(`.error`, `.lock`, -`.constraint`, `.json`, `.array`, `.range`, `.copy`), `api.query`, `envers`, `querydsl`, `cache`, `observation`, -`experimental`은 **라이브러리 API**다: 어떤 설정도 그것을 조립하지 않고, 서비스가 이 leaf를 `implementation`으로 받는 -자기 어댑터 leaf에서 부른다. 진입점과 각각을 증명하는 시험은 [README.md](README.md) 「라이브러리 API」에 있다. - -### Spring 조립 소유 - -`META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports`는 package-private 항목 둘을 내놓는다: -`PersistenceJpaAutoConfiguration`과 `PersistenceJpaRuntimeConfig`. Boot가 그 후보를 따로따로 읽으므로 **둘 다** -`app.persistence-jpa.enabled=true`를 요구한다. 첫째는 vendor·entity·repository와 capability 저장소 import를 가진다. -둘째는 provider runtime bean(`HibernateProviderPolicy`, `PostgreSqlRuntimeRoleVerifier`)만 기여한다. 트랜잭션 엔진은 -`SpringTransaction` 하나뿐이다. 두 번째 엔진(`SpringJpaTransactionExecutor`/`FullTransactionRetryCoordinator`)은 -2026-09-25에 지웠다 — `docs/capability-status.md`를 본다. 첫째 후보의 조건이 이웃 import 후보를 막아 준다고 기대지 -않는다. - -`enabled=false`는 bean만이 아니라 완전히 끄기다: `JpaActivationEnvironmentPostProcessor`(이 leaf의 `spring.factories`)가 -Boot의 `jdbc`/`hibernate`/`data.jpa`/`flyway` 자동 구성을 `spring.autoconfigure.exclude`에 붙인다. 그래서 DataSource, -pool, EntityManagerFactory, Flyway가 하나도 없다. - -소유자를 안전하게 지키는 PostgreSQL 멱등성도 같은 분할을 쓴다: 이 leaf는 `IdempotencyStorePort` 뒤의 실제 PostgreSQL -store를 만들고(`PostgreSqlIdempotencyStoreConfig`, `app.capabilities.idempotency.provider=postgresql`일 때만 켜진다), -`composition:idempotency`가 provider 고르기, TTL·lease·codec 정책, executor 만들기, 배타성 검증을 가진다. 그 provider를 -고르면 leaf는 `db/migration/jpa/core` + `db/migration/jpa/idempotency` Flyway stream도 적용하고 기동 때 capability -registry 행을 켜며(`IdempotencySchemaStream`, `app.runtime.migration-on-startup=false`이면 건너뛴다), PostgreSQL이 아닌 -data source를 거절하고, `IdempotencyReaper`를 돌린다. V1·JDBC 멱등성 store도 `jdbc` provider 값도 없다. - -이 모듈은 빌드 한 줄(`runtimeOnly project(':adapter:outbound:persistence-jpa')`)로 고르는 capability다. 템플릿의 기본 -조립은 이것을 싣지 않는다. 그래서 관계형 저장소가 있을 때만 뜻이 있는 것은 모두 여기 있고 모듈과 함께 켜진다: -migration 기동 순서, 해석된 datasource·버전 검증, OSIV·DDL·pool·TLS·vendor 안전, 걸러 낸 관리 endpoint·보고 -(`startup`), metric을 단 다중 인스턴스 lock(`lock`), readiness `db` 기여, 출하하는 설정 -(`config/module-defaults/persistence-jpa.yml`). 유스케이스 조립은 아니다: driven 어댑터가 유스케이스를 만들거나 부르면 -안 되므로 outbox relay는 `composition:outbox-relay`다. leaf에는 `dev.caskeleton.bootstrap` import가 하나도 없어야 한다. -기동 실패는 `adapter:outbound:support`(`support.startup`)를 거치고, 새 조립 도우미는 package-private로 둬서 배선 -실수로 `verifyJpaApiSurface`가 늘지 않게 한다. - -### 양보할 수 없는 것 - -- `GenericRepository`도 플랫폼 기반 repository도 없다. 도메인이 자기 repository를 가진다. -- `TransactionCompletionUnknownException`은 절대 재시도하지 않는다. `JpaFailureContext`는 재시도할 수 있는 - completion-unknown 실패를 나타내기를 거절하고, `SpringTransaction`은 아무것도 재시도하지 않는다. -- 재시도하는 호출자는 새 트랜잭션과 새 Persistence Context에서 유스케이스 전체를 다시 돌린다. -- OSIV는 모든 runtime profile에서 false다. schema 변경은 Flyway가 가지고 Hibernate는 검증만 한다. -- 이미 쓰이는 테이블을 잠그는 migration은 `SET LOCAL lock_timeout = '5s';`로 시작한다 - (`docs/jpa/migration-guide.md` "Bound the lock wait"). `MigrationLockWaitTest`가 그것이 없는 migration을 거절한다. 그 - 규칙 전에 릴리스한 migration 목록에는 새 migration을 넣지 않는다. 그 목록은 inspector가 문장을 새로 배우고 이미 - `main`에 있는 파일에서 그것을 찾았을 때만 늘어난다. -- Flyway는 PostgreSQL migration lock을 열린 트랜잭션이 아니라 세션 동안 쥔다. 아니면 `CREATE INDEX CONCURRENTLY` - migration이 Flyway를 영원히 기다린다: 모듈 기본값의 `spring.flyway.postgresql.transactional-lock: false`, 그리고 코드에서 - 만드는 모든 Flyway는 `FlywaySchemaPolicy.configure()`에서 시작한다(`JpaProductionArchitectureTest`가 - `Flyway.configure()`와 Flyway 설정을 직접 만드는 것 — `new FluentConfiguration()`, `new ClassicConfiguration()`, 하위 - 클래스 — 을 거절한다. `docs/jpa/migration-guide.md` "Who may change the schema"). -- metric tag, 예외 메시지, 로그는 SQL 매개변수, entity id, tenant id, 개인정보를 싣지 않는다. -- 계약은 실제 PostgreSQL에 대고 돈다. H2는 어떤 계약도 만족시키지 않는다. - -### 플랫폼 lane - -```bash -cd src -./gradlew :adapter:outbound:persistence-jpa:test # hermetic unit lane -./gradlew :adapter:outbound:persistence-jpa:jpaPlatformContractTest # real PostgreSQL -./gradlew :adapter:outbound:persistence-jpa:jpaPlatformMigrationTest # Flyway upgrade scenarios -./gradlew :adapter:outbound:persistence-jpa:jpaPlatformFailureTest # deadlock -./gradlew :adapter:outbound:persistence-jpa:jpaPlatformQueryPlanTest # EXPLAIN structure -./gradlew :adapter:outbound:persistence-jpa:jpaPlatformSecurityTest # runtime role privileges -./gradlew :adapter:outbound:persistence-jpa:jpaPlatformPoolContractTest # pool behaviour -# Release blocking composition is CI-owned; locally run the exact database qualification set: -./gradlew :adapter:outbound:persistence-jpa:jpaPlatformContractTest \ - :adapter:outbound:persistence-jpa:jpaPlatformMigrationTest \ - :adapter:outbound:persistence-jpa:jpaPlatformFailureTest \ - :adapter:outbound:persistence-jpa:jpaPlatformQueryPlanTest \ - :adapter:outbound:persistence-jpa:jpaPlatformSecurityTest \ - :adapter:outbound:persistence-jpa:jpaPlatformPoolContractTest -``` - -Docker를 쓰는 모든 lane은 실패하면 닫힌다. 고른 lane이 아무것도 찾지 못하거나 container가 시작하지 못하면 건너뛰기가 -아니라 오류다 — 건너뛴 계약은 아무도 시험하지 않은 데이터베이스에 대해 성공을 알린다. - -## 책임 - -- JPA 엔티티. -- Spring Data repository. -- 영속 mapper. -- repository 어댑터 구현. -- outbox append: 모델 하나. `JpaOutboxStore`가 `OutboxAppendPort`를 구현하고 `ValidatedIntegrationEvent`의 정확한 envelope - 바이트와 hash를 저장한다. claim은 그것으로 같은 이벤트를 되살린다. 정해진 metadata가 다 갖춰지지 않은 행은 읽을 수 - 없고 DEAD로 간다. 짐작으로 발행하지 않는다. `V19`는 발행하지 않은 정해진 형식 이전 행을 거절한다. -- outbox relay fencing: `claimBatch`가 claim의 행 lock 아래에서 claim한 relay(`lease_owner`)를 기록하고 - `lease_token`을 올린다(`V17`). `markPublished`/`markFailed`/`markDead`는 `event_id` + `IN_FLIGHT` + owner + token에 - 대한 조건부 UPDATE 하나이고 `APPLIED`/`STALE`을 돌려준다. 완료는 행을 읽어서 덮어쓰지 않는다. V2 outbox 세대는 - 2026-09-25에 지웠다(`docs/capability-status.md`). -- `TransactionPort` 구현(`SpringTransaction`) — 애플리케이션의 트랜잭션 의도와 Spring `PlatformTransactionManager` 사이의 - 다리. -- 감사 metadata 기반 + actor 이음매(`audit/AuditableEntity`, `audit/AuditContextPort`, `audit/DomainContextAuditContext`) — - 아래 「영속 감사 계약」을 본다. -- 모든 RDBMS vendor가 같이 쓰는 vendor SPI 확장점: - - `outbox/jpa/OutboxClaimRepository` — vendor 모듈이 claim 전략(예: FOR UPDATE SKIP LOCKED)을 구현한다. 구현은 그 - 옆 `outbox/postgresql`과 `outbox/h2`에 있다. - - `failure/SqlStateErrorMapping` — vendor 모듈이 vendor 전용 SQLState 행을 기여한다. - -## vendor 고르기 - -vendor 조립 둘이 이 모듈에 있고, 각각 자기 하위 패키지에 있으며, 각각 같은 SPI bean 둘(outbox claim, SQLState 대응)을 -등록한다: - -| vendor | 패키지 | 고르는 것 | schema 소유 | -| --- | --- | --- | --- | -| PostgreSQL | `.postgresql` | `app.persistence.vendor=postgresql`(기본값이기도 하다) | Flyway, `db/migration/postgresql` | -| H2 | `.h2` | `app.persistence.vendor=h2` | Hibernate `ddl-auto`, 엔티티만 | - -outbox와 멱등성 기능은 기능별, 그다음 vendor별로 조각을 모아 둔다: `outbox/{jpa,postgresql,h2}`와 -`idempotency/{jpa,postgresql}`. 어떤 claim repository를 등록할지는 여전히 위 vendor 설정이 정한다. 그 기능 클래스 중 -driver 타입을 import하는 것이 없으므로, 그것들이 `.postgresql` 밖에 있어도 -`PERSISTENCE_RDBMS_STAYS_VENDOR_NEUTRAL`이 계속 지켜진다. - -`config/PersistenceVendorSettings`가 선택자를 enum으로 바인딩한다. 그래서 모르는 값은 두 조립 중 어느 것도 읽지 않고 -`OutboxClaimRepository`가 없다는 오류로 나타나는 대신 기동 때 실패한다. 선택은 모듈이 정한다: 그 -`config/module-defaults/persistence-jpa.yml`이 모든 profile에서 vendor를 PostgreSQL로, `spring.flyway.enabled`를 -`APP_FLYWAY_ENABLED`(true)로 기본 설정한다. 조립 루트의 profile 파일은 더는 그것을 다시 적지 않는다(2026-11-01 -성숙도 리뷰 뒤로. 기본 조립 루트가 고르지 않은 capability의 설정을 알면 안 된다). H2는 `bootRunH2` 태스크가 -고르는, 개발자가 명시해서 빠지는 길이다. `PersistenceVendorProdSafetyValidator`(`startup`)는 어떤 -속성 출처가 주든 prod에서 H2를 거절한다. `bootRunH2`에서는 멱등성 provider가 `disabled`나 `redis`여야 한다: -`postgresql` provider는 기동 때 H2 data source를 거절한다. - -H2는 로컬 개발 저장소이지 두 번째 운영 대상이 아니다. migration 트리가 없으므로, migration에만 있는 테이블 — -capability schema registry, Spring Integration lock 테이블 — 은 H2에 없다. vendor 동시성과 migration 충실도는 -`postgresqlIntegrationTest`에 남는다. - -outbox claim은 H2가 돌리는 유일한 vendor 문장이고 내용이 같다 — H2 2.4.240은 `FOR UPDATE SKIP LOCKED`를 받고 잠긴 행을 -정말 건너뛰므로 claim이 뜻을 지킨다. `H2ClaimSqlTest`가 그것을 실제 H2에 대고 실행한다. H2에는 멱등성 store가 없다. - -### capability로 막은 store - -선택 capability 하나를 위한 어댑터는 이 모듈의 나머지와 달리 그 capability의 스위치를 단다. 지금은 `fileserver` -패키지가 그 경우다: 거기 있는 모든 `Jpa*` 어댑터는 -`@ConditionalOnProperty(prefix = "app.fileserver-platform", name = "enabled", havingValue = "true")`를 단다. - -그 막음이 없으면 이 모듈을 넣기만 한 조립 루트도 그 bean을 만들고, 각 bean에는 파일 서버 설정만 주는 협력 객체가 -필요하다. 지운 샘플 모듈이 쓰지도 않는 Fileserver 협력 객체 때문에 기동에 실패한 일이 그 예다. 아무도 켜지 않은 -capability의 store는 있으면 안 된다. - -## 허용 - -- `:application-core` -- `:domain-core` -- `:shared-contract` -- `:adapter:outbound:support`(타입 있는 기동 실패, EnvironmentPostProcessor 순서, readiness group, module-defaults 읽기) -- Spring Data JPA와 Spring transaction. - -## 금지 (Forbidden) - -- `adapter-web`, `app-bootstrap`, `adapter:outbound:support`를 뺀 다른 outbound 어댑터. -- 표현 계층 DTO. -- 업무 정책 판단. -- 영속 어댑터 안에 숨긴 유스케이스 조율. -- repository 어댑터가 애플리케이션 흐름을 감싸 `@Transactional`을 여는 것 — 포트를 가로지르는 트랜잭션은 애플리케이션 - 유스케이스가 `TransactionPort`로 가진다. 어댑터 안의 트랜잭션은 포트 메서드 자체가 원자적이어야 하는 저장 프로토콜을 - 정할 때만 허용한다(예: durable operation claim·읽기, live event 위치 할당 + insert). - [application-core/CLAUDE.md](../../../application-core/CLAUDE.md)를 본다. -- **DB driver**(`org.postgresql..`, `org.h2..`)나 **`org.flywaydb.database.postgresql..`** — vendor 전용이라 이 모듈의 - 맞는 vendor 패키지(`.postgresql`, `.h2`)에만 둔다. NoSQL 전용 의존은 앞으로 생길 자기 모듈에만 둔다. - `CleanArchitectureTest`의 ArchUnit `PERSISTENCE_RDBMS_STAYS_VENDOR_NEUTRAL`과 `PERSISTENCE_RDBMS_STAYS_NEUTRAL_OF_H2`가 - 강제한다. -- NoSQL 어댑터 코드. MongoDB·Redis·DynamoDB 어댑터는 이 모듈의 자식이 아니라 이웃 모듈이다. -- registry가 허용하지 않은 이웃 영속 어댑터나 inbound·outbound 어댑터. - -## TransactionPort 구현 계약 - -`SpringTransaction`은 모드마다 `TransactionTemplate`을 하나씩 미리 만든다: - -| 모드 | 전파 | 격리 | 읽기 전용 | timeout | -|---|---|---|---|---| -| `inWrite` | `REQUIRED` | `READ_COMMITTED`(pool) | `false` | `app.persistence-jpa.transaction.write-timeout`(30 s) | -| `inRootWrite` | `REQUIRED` | `READ_COMMITTED`(pool) | `false` | `inWrite`와 같음 | -| `inRead` | `REQUIRED` | `READ_COMMITTED`(pool) | `true` | `app.persistence-jpa.transaction.read-timeout`(30 s) | -| `inNew` | `REQUIRES_NEW` | `READ_COMMITTED`(pool) | `false` | 30 s, 고정 | - -격리 수준은 template이 아니라 pool에 고정한다: template은 `ISOLATION_DEFAULT`를 쓰고, 모듈 기본값이 -`spring.datasource.hikari.transaction-isolation: TRANSACTION_READ_COMMITTED`를 정하며(물리 연결마다 한 번 적용), -`HikariPoolConstraintValidator`가 다른 수준이면 기동을 거절한다. template마다 수준을 대면 Spring이 begin마다 -`getTransactionIsolation()`을 부르고, pgjdbc는 그것에 `SHOW TRANSACTION ISOLATION LEVEL` 왕복으로 답했다. - -모든 모드에는 시간 한계가 있다(2026-11-01부터). Spring이 남은 시간을 문장마다 넘기므로 느린 query나 lock 대기는 서버가 -취소하고(`57014` → `DB_QUERY_CANCELED`), 다음 문장 전에 기한이 지난 경우도 같은 코드를 받는다: JDBC 경로에서는 Spring의 -`TransactionTimedOutException`, JPA 경로(`JpaTransactionManager`, 운영)에서는 Hibernate 자신의 `TransactionException`이다. -후자는 SQLState가 없고, `SpringTransaction`이 기한이 지났음을 알기 때문에 분류된다(`translateAfterDeadline`). 기한 뒤에 -던진 업무 예외는 바꾸지 않고 넘긴다. - -미리 만든 template은 만든 뒤 바뀌지 않아서, 동시 호출자가 서로의 재설정을 볼 수 없다. `inRootWrite`는 미리 만든 쓰기 -template을 다시 쓰지만, 먼저 `TransactionSynchronizationManager.isActualTransactionActive()`를 검사한다. 실제 바깥 -트랜잭션이 있으면 action이나 `PlatformTransactionManager`를 부르기 전에 반드시 -`NestedRootTransactionRejectedException`을 던진다. `NEVER`나 `REQUIRES_NEW`를 쓰면 안 된다. - -`inRootWrite`는 `TransactionTemplate.execute`가 커밋한 뒤에만 action 값을 돌려준다. 커밋이 실패하면 트랜잭션 예외를 -올리고 호출자에게 성공 값을 돌려주지 않는다. - -### `inNew` 풀 크기 제약 (feature-application-port-usecase-contract) - -`REQUIRES_NEW`는 바깥 트랜잭션의 연결을 쥔 채 새 물리 JDBC 연결을 얻는다. pool은 다음을 만족하게 잡는다: - -``` -hikari.maximumPoolSize >= (concurrent_threads × (1 + max_inNew_depth)) + 1 -``` - -레코드마다 `inNew`를 부르는 반복문은 금지다(pool 고갈 + 교착 위험). 레코드를 `inNew` **하나** 안에서 묶어 처리하거나, -반복문을 트랜잭션 밖으로 뺀다. - -## 영속 실패 번역 계약 (feature-persistence-failure-baseline) - -날것의 Spring `DataAccessException`(과 그 안의 JPA 예외·SQLState·제약 이름)은 절대 표현 계층에 닿으면 안 된다. -`failure/PersistenceExceptionTranslator`가 `DataAccessException`을 SQLState로 아래 §SQLState → 오류 코드 표와 대조해 -분류하고, `DB_*` `OperationalError` 코드 하나를 실은 프레임워크 중립 `shared.error.PersistenceFailureException`을 돌려준다. - -**표준 행(core):** - -| SQLState | code | category | http | retryable | -|---|---|---|---|---| -| `08*` | `DB_UNAVAILABLE` | `TRANSIENT_DEPENDENCY` | 503 | true | -| `40001` | `DB_SERIALIZATION_FAILURE` | `CONFLICT` | 409 | true | -| `23502` | `DB_NULL_VIOLATION` | `DATA_INTEGRITY` | 409 | false | -| `23503` | `DB_FK_VIOLATION` | `DATA_INTEGRITY` | 409 | false | -| `23505` | `DB_UNIQUE_VIOLATION` | `CONFLICT` | 409 | false | -| `23514` | `DB_CHECK_VIOLATION` | `DATA_INTEGRITY` | 409 | false | - -**vendor 전용 행(vendor 모듈이 `SqlStateErrorMapping` SPI로 기여):** - -| SQLState | code | vendor | -|---|---|---| -| `40P01` | `DB_DEADLOCK` | PostgreSQL(`.postgresql` 패키지) | -| `55P03` | `DB_LOCK_TIMEOUT` | PostgreSQL | -| `25P03` | `DB_IDLE_IN_TX_TIMEOUT` | PostgreSQL | -| `57014` | `DB_QUERY_CANCELED` | PostgreSQL | -| `57P01`, `57P02` | `DB_UNAVAILABLE`(커밋 전. 커밋 중이면 completion-unknown) | PostgreSQL | -| `23513` | `DB_CHECK_VIOLATION` | H2(`.h2` 패키지) — H2는 CHECK를 core 표가 대응시키는 표준 23514가 아니라 23513으로 알린다 | -| `HYT00` | `DB_QUERY_CANCELED` | H2 — H2는 문장 timeout과 lock timeout을 상태 하나로 합친다 | - -PostgreSQL 행은 두 번째 표가 아니다: 2026-11-01 전에는 손으로 관리하던 두 번째 표가 이미 어긋나 있었다. -`PostgreSqlSqlStateErrorMapping`이 그 행을 `PostgreSqlFailureClassifier`(SQLState → `FailureCategory`)와 -`FailureCategory.operationalError()`(category → 코드)에서 끌어낸다 — 라이브러리 `PostgreSqlExceptionTranslator`가 쓰는 -것과 같은 분류다 — 그리고 위 표준 행, 전용 코드가 없는 category(`INTERNAL_ERROR`), `COMPLETION_UNKNOWN`(단계에 -따라 다르다)을 뺀다. PostgreSQL 상태를 더하려면 `PostgreSqlState`와 classifier에 더한다. 두 경로가 어떤 상태에서든 -다르면 `SqlStateClassificationParityTest`가 실패한다. - -**SQLState가 없고 타입으로 분류:** 진 `@Version` 경쟁(`OptimisticLockingFailureException`, JPA -`OptimisticLockException`) → `DB_OPTIMISTIC_CONFLICT`(409). 만료된 Spring 트랜잭션 기한(`TransactionTimedOutException`) -→ `DB_QUERY_CANCELED`. `SpringTransaction`이 시작한 트랜잭션의 기한이 지난 뒤의 다른 영속 실패(JPA, Spring -data-access, Spring transaction 예외) → `DB_QUERY_CANCELED`. - -**커밋 단계(`translateCommitFailure`, ADR-JPA-003):** action이 돌아왔고 `SpringTransaction`이 자기가 시작한 쓰기 -트랜잭션을 커밋하는 중이면, `08*`, `40003`, vendor가 기여한 종료 상태(`SqlStateErrorMapping.commitOutcomeUnknownStates()`: -PostgreSQL `57P01`, `57P02`), SQLState 없는 전송 끊김을 가진 실패는 `DB_UNAVAILABLE`이 아니라 -`TransactionCompletionUnknownException` → `DB_COMPLETION_UNKNOWN`(500, 절대 재시도하지 않음)이 된다: 서버가 이미 커밋했을 -수 있다. 서버가 분명히 거절한 커밋(예: 미뤄진 `23505`)은 위 자기 행을 지킨다. 읽기 전용 커밋은 `DB_UNAVAILABLE`을 지킨다. - -- `DataAccessException`을 잡는 repository 어댑터는 `translator.translate(ex)`를 부르고 carrier를 다시 던진다 - (`ifPresent(e -> { throw e; })`). 빈 결과는 모르는 SQLState라는 뜻이다 — 원래 예외를 다시 던져 web catch-all이 일반 - `INTERNAL` envelope으로 답하게 한다(새는 것 없음). -- category 정본은 값 10개의 `Category` enum이다 — `PERSISTENCE` category는 **없다**(설계 기록 §Audit CATEGORY_DRIFT). - -## 영속 감사 계약 (feature-persistence-auditing-contract) - -감사 metadata(`created_at` / `updated_at` / `created_by` / `updated_by`)는 기반 관심사이고 `domain-core`에 닿으면 안 된다. -`audit/AuditableEntity` `@MappedSuperclass`에만 있다. 도메인 aggregate의 영속 엔티티가 그것을 상속해서 고른다(생성 -명령이 만드는 서비스 persistence leaf의 엔티티가 그렇게 한다). 도메인 aggregate 자체는 감사 필드를 하나도 갖지 않는다. -ArchUnit `DOMAIN_IS_PURE`(`jakarta.persistence..` 없음)와 `DOMAIN_ENTITIES_DO_NOT_CARRY_AUDIT_FIELDS`(`..domain..` 아래에 -`createdAt`/`updatedAt`/`createdBy`/`updatedBy` 필드 없음)가 강제한다. - -- **잡기 = 손으로 명시해 넣기(지금 기본).** repository 어댑터가 생성자로 `Clock`과 `AuditContextPort`를 받고 `save`에서 - 감사 값을 넣는다: INSERT(version null) → `initializeAudit(now, actor)`. UPDATE(version 있음) → 저장된 `created_*`를 그대로 - 넘기고 + `applyModification(now, actor)`. `created_*`는 `updatable = false`다. -- **actor 이음매.** `AuditContextPort.currentActor()`는 runtime-context 전파 이음매를 읽고, principal이 묶여 있지 않으면 - (scheduler / Flyway / 익명) `"system"`으로 물러선다. actor 값의 뜻은 - feature-authentication-authorization-contract가 가진다(여기서는 UNSUPPORTED). 타입은 `String`으로 고정한다. -- **빠지는 것.** `IdempotencyRecordEntity`(자기 `created_at`, `updated_at` 없음) 같은 기반·불변 엔티티는 `AuditableEntity`를 - 상속하지 **않는다**. `version`·낙관적 lock은 이 감사 기반이 아니라 feature-persistence-failure-baseline / - feature-transaction-concurrency-contract가 가진다. -- **자랄 길(미룸).** 트리에 두 번째 감사 구현은 없다. 손으로 넣는 것이 실수가 너무 잦아지면, 정해진 `AuditableEntity` - 계약을 `created_*`/`updated_*` schema, actor 한계, `Clock`, `AuditContextPort` 뜻을 지키면서 한 번에 Spring Data - listener로 옮긴다. bulk·native `@Query` UPDATE도 listener를 지나지 않으므로 계속 감사 열을 명시해 넣어야 한다. - -## MapStruct 생성 mapper 예외 (feature-architecture-enforcement-rules) - -영속 mapper에 MapStruct를 들이면, 생성된 mapper 클래스에 `javax.annotation.processing.Generated`가 붙는다. mapper 경계 -위반을 금지하는 아키텍처 규칙은 반드시 ArchUnit predicate로 생성 코드를 뺀다: - -```java -import javax.annotation.processing.Generated; - -classes() - .that().resideInAPackage("..adapter.persistence.mapper..") - .and().areNotAnnotatedWith(Generated.class) - .should() /* ... boundary rule ... */; -``` - -> 애너테이션 FQN에 주의한다: MapStruct는 `javax.annotation.processing.Generated`를 쓴다. Spring AOT는 -> `org.springframework.aot.generate.Generated`를 쓴다 — 둘을 섞지 **않는다**. 예외는 반드시 빼려는 빌드 단계가 기대하는 -> 바로 그 애너테이션으로 범위를 잡는다. - -지금 ca-tmpl mapper는 손으로 쓴 것이라 ArchUnit에 MapStruct 예외를 아직 배선하지 않았다 — 생성을 더할 때 위 -predicate를 따르고, fixture mapper로 red/green 시험을 더한다. - -## NoSQL 확장 규칙 - -`adapter-persistence-nosql-core`를 미리 만들지 않는다. NoSQL 저장소는 모델과 운영 계약이 서로 다르다. 실제 MongoDB, -Redis, DynamoDB 어댑터가 필요해지면 이웃 모듈을 만든다: - -```text -adapter-persistence-mongodb -adapter-persistence-redis -adapter-persistence-dynamodb -``` - -그런 모듈은 application·domain 포트를 직접 구현하고 `adapter:outbound:persistence-jpa`에 의존하면 안 된다. - -## 테스트 - -```bash -cd src -./gradlew :adapter:outbound:persistence-jpa:test --console=plain -``` +@AGENTS.md diff --git a/src/adapter/outbound/persistence-jpa/README.md b/src/adapter/outbound/persistence-jpa/README.md index 35815116..4688c323 100644 --- a/src/adapter/outbound/persistence-jpa/README.md +++ b/src/adapter/outbound/persistence-jpa/README.md @@ -3,9 +3,9 @@ RDBMS/JPA 퍼시스턴스 베이스 모듈. 패키지 루트: `dev.caskeleton.adapter.persistence`. 허용/금지 의존, 테스트 명령, 그리고 **계약 테이블**(TransactionPort 모드표, SQLState → Error -Code 매트릭스, auditing 계약, 분산 락 provider 선택표)의 SSOT 는 [CLAUDE.md](CLAUDE.md) 다. +Code 매트릭스, auditing 계약, 분산 락 provider 선택표)의 SSOT 는 [AGENTS.md](AGENTS.md) 다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를 모아둔 참조용 기록이다 — 코드를 읽다 -"왜 이렇게 했나"가 궁금할 때 본다. 표가 CLAUDE.md 에 있으면 여기서는 중복하지 않고 그 근거만 +"왜 이렇게 했나"가 궁금할 때 본다. 표가 AGENTS.md 에 있으면 여기서는 중복하지 않고 그 근거만 적는다. ## capability 모듈로 쓰기 — 제공하는 것, 추가할 한 줄, 필요한 env @@ -107,7 +107,7 @@ promotion gate, 생성하는 곳 없는 `JpaTransactionObservation` 등)은 `doc readOnly 를 바꿔 쓰면 같은 빈을 공유하는 동시 요청 사이에 race window 가 생긴다. 모드별로 (`WRITE` / `READ_ONLY` / `REQUIRES_NEW`) 템플릿을 생성 시점에 하나씩 만들어 두면 그 race 가 사라지고, 각 모드를 따로 감사(audit)할 수 있다. 세 템플릿 모두 isolation 을 `READ_COMMITTED` -로 고정한다(모드표는 CLAUDE.md §TransactionPort implementation contract). +로 고정한다(모드표는 AGENTS.md §TransactionPort implementation contract). ### 왜 `inRootWrite`가 별도 템플릿이나 `NEVER` propagation을 만들지 않나 `inRootWrite`의 실행 속성은 `inWrite`와 같은 `WRITE + REQUIRED + READ_COMMITTED`라 기존 @@ -179,7 +179,7 @@ Spring Boot 메인 클래스는 `dev.caskeleton.bootstrap` 에 있어서, `@Auto ## failure — 퍼시스턴스 실패 변환 SPI -매트릭스(SQLState → `DB_*` 코드, category, http, retryable)의 SSOT 는 CLAUDE.md §Persistence +매트릭스(SQLState → `DB_*` 코드, category, http, retryable)의 SSOT 는 AGENTS.md §Persistence failure translation contract 다. 여기서는 SPI 구조와 fallback 근거만 적는다. ### SPI-pluggable 설계 (vendor 추출) @@ -502,7 +502,7 @@ stream migration이 중단되면 history/registry/object 상태를 먼저 확인 ## lock — 분산 락 -provider 선택표(flag → bean → registry)의 SSOT 는 CLAUDE.md(또는 app-bootstrap 와이어링)다. +provider 선택표(flag → bean → registry)의 SSOT 는 AGENTS.md(또는 app-bootstrap 와이어링)다. 여기서는 어댑터/설정 결정 근거만 적는다. ### `LockRegistryDistributedLock` 계약 diff --git a/src/adapter/outbound/persistence-mongo/AGENTS.md b/src/adapter/outbound/persistence-mongo/AGENTS.md new file mode 100644 index 00000000..c3110014 --- /dev/null +++ b/src/adapter/outbound/persistence-mongo/AGENTS.md @@ -0,0 +1,157 @@ +# adapter:outbound:persistence-mongo — 모듈 규칙 + +## 등록 정보 + +- 모듈 ID: `adapter-outbound-persistence-mongo` +- Gradle 경로: `:adapter:outbound:persistence-mongo` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:persistence-mongo:test --console=plain` +- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. +- registry 정본: `src/config/architecture/modules.json`. + +패키지 루트: `dev.caskeleton.adapter.outbound.mongo`. driven(outbound) 어댑터 — 골라 쓰는 MongoDB 문서 영속 +플랫폼이다. 설계 근거는 [README.md](README.md)에 있다. 설계 패키지가 가정한 모듈 배치를 이 leaf에 대응시킨 것은 +`docs/mongodb/repository-adaptation.md`에 있고, 그 대응이 바뀌면 고칠 파일이 그것이다. + +## 책임 + +- 가짜 업무 도메인을 싣지 않고, 골라 쓰는 Mongo client, template, **플랫폼 정책** surface를 준다. 실제 fork가 자기 + 문서, repository, mapper, application·domain 포트 구현을 더한다. +- 멱등성·outbox·lock을 Mongo 위에 다시 구현하지 **않는다**(그것은 JPA에만 남는다). +- 있으면 켜진다: `app.persistence-mongo.enabled=false`가 아니면 `MongoRootAutoConfiguration`과 그것이 import하는 + 모든 것이 돈다(`matchIfMissing = true`. 출하하는 `config/mongo.yml`이 `APP_PERSISTENCE_MONGO_ENABLED`를 대응시키고 + 기본은 `true`). 빌드에 없는 것이 보통의 꺼진 상태다. 연결 URI와 데이터베이스는 Spring의 표준 `spring.mongodb.*` + 설정에서 오고, 플랫폼 profile은 `app.persistence-mongo.platform.*`에서 온다. + 연결 출처는 실패하면 닫힌다: `spring.mongodb.uri` / `SPRING_MONGODB_URI`가 비어 있지 않거나, 고른 typed profile이 + `uri-secret`을 주고 배포가 `MongoCredentialResolver`를 줘야 한다. typed profile은 문서용만이 아니다: + `MongoProfileClientSettingsAutoConfiguration`이 `MongoClientSettingsFactory`를 Boot의 실제 + `MongoClientSettings.Builder`에 가장 낮은 우선순위로 적용하므로, 그 TLS, Stable API, timeout, pool 정책이 일반 + 기본값을 덮는다. typed profile이 없으면(URI만) `MongoUriOnlyClientDefaults`가 Boot가 connection string을 적용하기 + **전에** 유한한 socket·connect·server selection timeout과 pool 한계를 적용하므로, URI 매개변수가 여전히 이긴다. + 자기 설정 키는 없다. +- 쓰는 쪽: 서비스 자신의 어댑터 leaf가 이 leaf를 `implementation`으로 받는다. 절차는 + `docs/mongodb/consumer-leaf-guide.md`다. 작동하는 예(문서, mapper, repository, 포트 구현)는 시험 소스 패키지 + `…mongo.example`이고, `mongoStableContractTest`가 돌린다. +- `META-INF/spring.factories`로 등록한 `MongoDefaultsEnvironmentPostProcessor`가 `config/mongo.yml`을 가장 낮은 + 우선순위로 읽고, 명시한 `enabled=false`이면 Boot 4의 Mongo 자동 구성(Boot 자신의 등록 파일에서 읽는다)을 + `spring.autoconfigure.exclude`에 붙인다. +- surface는 두 가지다. 자동 구성 bean(README.md 「자동 구성」에 적힌 것)은 `enabled=true`로 켜진다. 나머지는 모두 + **라이브러리 API**다(README.md 「라이브러리 API」): 서비스 자신의 어댑터 leaf가 이 leaf를 `implementation`으로 + 받아 타입을 만든다. 라이브러리 API는 bean으로 등록하지 않고 자기 속성이 없다. +- Mongo health 연동은 leaf가 가진다. MongoRootAutoConfiguration이 내부 MongoPlatformHealthConfiguration을 import하고, + 그것이 MongoPlatformHealthIndicator를 안정된 bean 이름 mongoPlatformHealthContributor 아래 Boot의 HealthIndicator + SPI에 맞춘다. 바깥 endpoint 노출은 여전히 애플리케이션 Actuator 노출 정책이 정한다. + +## 허용 + +- 프로젝트 의존 둘. `Sha256`과 `HmacSha256` 도우미를 위한 `shared-contract`(테넌트 관찰 키, admin 명령 digest, + credential fingerprint, keyset cursor tag. `MongoDigestOutputTest`가 출력을 고정한다). `SecretSourcePort`만을 위한 + `application-core`. registry 항목의 `allowed_dependencies`는 `["application-core", "shared-contract"]`이고 빌드가 + 실제로 쓰는 것과 맞는다. `MongoProfileClientSettingsAutoConfiguration`의 bridge가 typed profile의 `uri-secret`을 + 배포가 설정한 비밀 값 backend로 해석한다. `verifyCleanArchitectureDependencies`는 해석된 edge가 선언된 것의 + 부분집합인지만 보므로 쓰지 않는 허가는 매번 통과한다. `MongoRegistryPermissionParityTest`가 반대 방향을 보고 두 + 집합이 다르면 실패한다. +- 서비스는 `app-bootstrap/build.gradle`에서 주석 처리한 한 줄 + `runtimeOnly project(':adapter:outbound:persistence-mongo')`로 이 leaf를 고른다. 기본 조립은 싣지 않는다. leaf는 + imperative만이다: reactive 쌍둥이(`reactive/**`, reactive 트랜잭션·세션), change-stream 소비자, change-stream → + 메시징 bridge는 2026-09-25에 지웠다(`docs/capability-status.md`). 그래서 leaf는 reactive starter도 + reactive-streams driver도 싣지 않는다(`MongoReactiveDriverAbsenceTest`). +- 외부 의존: (sync) Mongo starter, spring-boot-autoconfigure, spring-boot-health, micrometer-core, slf4j-api, + configuration processor. Boot Health가 Jackson 애너테이션을 싣지만 런타임 JSON 직렬화는 애플리케이션의 몫이라서 + Jackson 애너테이션은 compile 전용이다. 버전은 공용 Spring Boot BOM에서 온다. driver 버전을 직접 고정하지 않는다. +- 시험 전용: ArchUnit, Testcontainers(`mongodb`, `toxiproxy`). + +## 금지 (Forbidden) + +- inbound 어댑터, 이웃 outbound 어댑터, `app-bootstrap`(ArchUnit `OUTBOUND_ADAPTERS_*` 규칙 묶음). +- 운영 코드에 자리표시용 `Example*` 문서, repository, record, 어댑터 타입을 싣기. +- 따로 승인된 계약 없이 Mongo 위에 멱등성·outbox·lock을 더하기. +- 줄 안에 완전한 이름으로 쓴 타입 참조, 파일 하나에 공개 최상위 타입 둘 이상. + +### 패키지 경계 규칙 (`MongoModuleBoundaryTest`) + +설계의 모듈 의존 표를 그대로 옮긴 것이다. 하나라도 어기면 빌드가 실패한다: + +- `…mongo.api..`는 Spring, MongoDB driver, BSON, Reactor를 import하지 않는다. 프레임워크 없는 핵심 계약이다. + `api/package-info.java`가 이유를 적는다. +- Stable 패키지는 `…mongo.advanced..`에 의존하지 않는다. +- 운영 패키지는 `…mongo.testkit..`에 의존하지 않는다. +- `query` ↛ `aggregation`, `schema` ↛ 실행 패키지, `observation` ↛ 실행 패키지, `migration` ↛ `migration.flamingock`. + +### 일관성에 묶인 template + +`MongoConsistencyBinder`는 일관성 profile마다 `MongoTemplate`을 하나 끌어낸다. Spring Data는 template의 지원 계약에 +setter만 내놓고 getter를 내놓지 않는다. 그래서 따라가야 하는 부분 — write-concern resolver, 쓰기 결과 검사, +lifecycle 이벤트, entity callback과 auditing을 주는 `ApplicationContext` — 을 `MongoTemplateSupportContract`로 명시해 +넘긴다. 여기서 private 필드에 대한 리플렉션은 금지다. context 밖에서 프로그램으로 callback을 등록한 template은 +묶인 경로로 다시 만들 수 없다. 그 설정은 소리 없이 버리지 않고 지원하지 않는 것으로 둔다. + +### 공개 surface + +jar 하나 안의 모든 공개 최상위 타입이므로, `public`은 어느 패키지에 있든 모든 채택자에게 공개다. +`verifyMongoApiSurface`(`check` 안)가 surface를 개수를 담은 `docs/architecture/mongo-api-surface.txt`와 비교한다. +늘리려면 `updateMongoApiSurface -PapproveMongoApiSurfaceChange`가 필요하고, 그것은 리뷰 결정이다. + +아키텍처 규칙 catalog(`…mongo.architecture`)는 운영이 아니라 **testkit** source set에 있다: ArchUnit 입력이고, 그것을 +싣으면 모든 쓰는 쪽의 runtime classpath에 규칙 글이 올라갔다. 같은 이유로 릴리스 gate도 testkit 전용이고, 구현은 +둘이 아니라 하나다: `…mongo.testkit.release`가 lane이 쓴 JUnit XML을 읽고, `scripts/verify-mongodb-platform.sh`와 +`src/adapter/outbound/persistence-mongo/release/release-contracts.json`이 그것을 돌린다. 운영 classpath에 있던 두 번째 +짝 — 손으로 만든 category 이름 집합과 그것을 검사한 gate — 은 자기 시험 말고는 호출자가 없었고 category 뒤에 정본도 +없었다. 옮기지 않고 없앴다. + +아직 남았고, 리뷰 정리의 일부로 일부러 하지 않은 것: 구현 패키지를 `internal` 루트 아래로 옮기고 그 안의 가시성을 +낮추는 일. 약 200개 파일에 걸친 기계적 변경이라 자기 커밋에 둔다. 그 뒤에는 위 snapshot이 surface가 실제로 +줄었다는 증거가 된다. + +### credential과 운영 profile + +운영 `MongoProfileProperties`는 TLS, 인증, 엄격한 Stable API, standalone이 아닌 topology, 유한한 양의 timeout을 +선언해야 한다. `validate()`가 그것을 모두 강제한다. URI는 `secret://` 참조이고, 그것을 connection string으로 바꾸는 +것은 `MongoCredentialResolver`뿐이다 — 값을 호출자가 준 함수에 넘기고 돌려주지 않으니, credential은 필드나 bean +속성이나 로그 줄이 아니라 호출 한 번의 지역 변수다. + +`platform.profiles`가 비어 있지 않으면 채택은 일부러 실패하면 닫힌다. 조립 변경 하나에서 데이터 plane +`MongoCredentialResolver`와 함께 `MongoTopologyProbe`, `MongoSecurityProfile`, admin `MongoCredentialReference`, +`MongoSchemaVersionRange`를 준다. README.md에 필드 14개짜리 운영 profile 예가 다 있다. profile을 조금씩 주며 그 +요구를 기동 실패 하나씩으로 알아내는 것은 받아들인 채택 길이 아니다. + +기본 resolver는 `SecretSourcePort` 위의 bridge다(`MongoCredentialResolver.fromSecretSource`. 그 포트에 bean이 있고 +다른 resolver가 없을 때 등록한다). 키는 Redis·HTTP client 모듈처럼 참조의 마지막 경로 조각이다. 싣지 않은 것: +실제 인증서를 가진 container가 필요한 TLS lane(믿는 CA, 틀린 CA, hostname 불일치, 만료된 인증서). 교체 순서 — 새 +generation 준비, traffic 전환, 옛 lease 비우기, 닫기 — 는 `MongoClientGenerationConcurrencyTest`가 덮는다. + +### 문체가 아닌 플랫폼 불변식 + +- 트랜잭션 본문 재시도와 커밋 재시도는 **따로 도는 반복문**이다: 본문 시도마다 새 세션, 모르는 커밋에는 커밋만 + 재시도. 커밋이 모호해진 뒤에는 본문을 다시 돌리지 않는다(`MongoTransactionRetryCoordinator`, ADR-MONGO-003). +- `MongoExecutionOutcome`의 모호한 값 둘을 성공이나 실패로 뭉개면 안 된다. +- BSON 표현은 라이브러리 기본값이 아니라 `MongoTypeRepresentationManifest`에서 온다(ADR-MONGO-002). +- index와 validator 변경은 manifest와 admin plane을 거친다. 모든 drop은 소유권이 막는다(ADR-MONGO-004). +- 모든 구체 Advanced 타입은 `@MongoAdvancedEntryPoint(capability)`나 `@MongoAdvancedPolicy`를 단다. entry point는 + `MongoAdvancedCapabilityGuard`를 받고, 존재하기 전에 `require`를 부른다. `MongoAdvancedRules`가 두 절반을 강제한다. + 「실행되는 것은 막는다」가 「누가 기억해 낸 것은 막는다」가 되지 않게 하는 것이 분류 규칙이다. +- flag에는 설정 속성이 없다. Advanced 타입은 라이브러리 API다: 채택자의 어댑터가 코드로 + `MongoAdvancedCapabilityFlags`와 guard를 만든다. Stable 자동 구성은 `..advanced..` 아래의 어떤 것도 참조하면 안 + 된다. +- 이 leaf가 바인딩하는 모든 설정 키는 동작을 바꿔야 한다. 아무것도 읽지 않는 키나, 효과가 기동 실패뿐인 키는 + 문서로 남기지 않고 지운다(AGENTS.md capability 규칙 3). `docs/capability-status.md`가 무엇을 왜 지웠는지 적는다. +- 인터페이스는 이 leaf 안에 구현이 있을 때만 싣는다. Search, vector, time series, GridFS는 계약만 있었고 + 2026-09-25에 지웠다. +- observation tag는 `MongoObservationConvention`의 허용 목록으로 제한한다. + +## 테스트 + +`MongoCapabilityActivationTest`는 실제 `SpringApplication`을 띄워 있음 = 켜짐, 명시한 `enabled=false` = client· +template·플랫폼 bean 없음(Boot의 Mongo 자동 구성 포함)을 증명한다. `MongoPersistenceConfigTest`는 타입 있는 켜기 +바인딩과, 네트워크 연결 없이 mock `MongoClient`와 실제 `MongoTemplate`으로 켜진 기반을 덮는다. + +밀폐된 계약 시험은 `@Tag("mongodb-contract")`를 달고 `check`가 의존하는 `mongoStableContractTest`에서 돈다. container +lane은 `mongodb-replicaset` / `mongodb-failover`를 달고 자기 태스크에서만 돈다. 기본 `test` 태스크는 그것을 뺀다. +`check` 안에 Docker가 필요한 lane이 있으면 사람들이 `check`를 건너뛰게 되기 때문이다. + +```bash +cd src +./gradlew :adapter:outbound:persistence-mongo:check --console=plain +``` + +릴리스 gate는 저장소 루트에서 돈다: `scripts/verify-mongodb-platform.sh`(Stable)와 +`scripts/verify-mongodb-advanced.sh`(Advanced). diff --git a/src/adapter/outbound/persistence-mongo/CLAUDE.md b/src/adapter/outbound/persistence-mongo/CLAUDE.md index c3110014..43c994c2 100644 --- a/src/adapter/outbound/persistence-mongo/CLAUDE.md +++ b/src/adapter/outbound/persistence-mongo/CLAUDE.md @@ -1,157 +1 @@ -# adapter:outbound:persistence-mongo — 모듈 규칙 - -## 등록 정보 - -- 모듈 ID: `adapter-outbound-persistence-mongo` -- Gradle 경로: `:adapter:outbound:persistence-mongo` -- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:persistence-mongo:test --console=plain` -- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. -- registry 정본: `src/config/architecture/modules.json`. - -패키지 루트: `dev.caskeleton.adapter.outbound.mongo`. driven(outbound) 어댑터 — 골라 쓰는 MongoDB 문서 영속 -플랫폼이다. 설계 근거는 [README.md](README.md)에 있다. 설계 패키지가 가정한 모듈 배치를 이 leaf에 대응시킨 것은 -`docs/mongodb/repository-adaptation.md`에 있고, 그 대응이 바뀌면 고칠 파일이 그것이다. - -## 책임 - -- 가짜 업무 도메인을 싣지 않고, 골라 쓰는 Mongo client, template, **플랫폼 정책** surface를 준다. 실제 fork가 자기 - 문서, repository, mapper, application·domain 포트 구현을 더한다. -- 멱등성·outbox·lock을 Mongo 위에 다시 구현하지 **않는다**(그것은 JPA에만 남는다). -- 있으면 켜진다: `app.persistence-mongo.enabled=false`가 아니면 `MongoRootAutoConfiguration`과 그것이 import하는 - 모든 것이 돈다(`matchIfMissing = true`. 출하하는 `config/mongo.yml`이 `APP_PERSISTENCE_MONGO_ENABLED`를 대응시키고 - 기본은 `true`). 빌드에 없는 것이 보통의 꺼진 상태다. 연결 URI와 데이터베이스는 Spring의 표준 `spring.mongodb.*` - 설정에서 오고, 플랫폼 profile은 `app.persistence-mongo.platform.*`에서 온다. - 연결 출처는 실패하면 닫힌다: `spring.mongodb.uri` / `SPRING_MONGODB_URI`가 비어 있지 않거나, 고른 typed profile이 - `uri-secret`을 주고 배포가 `MongoCredentialResolver`를 줘야 한다. typed profile은 문서용만이 아니다: - `MongoProfileClientSettingsAutoConfiguration`이 `MongoClientSettingsFactory`를 Boot의 실제 - `MongoClientSettings.Builder`에 가장 낮은 우선순위로 적용하므로, 그 TLS, Stable API, timeout, pool 정책이 일반 - 기본값을 덮는다. typed profile이 없으면(URI만) `MongoUriOnlyClientDefaults`가 Boot가 connection string을 적용하기 - **전에** 유한한 socket·connect·server selection timeout과 pool 한계를 적용하므로, URI 매개변수가 여전히 이긴다. - 자기 설정 키는 없다. -- 쓰는 쪽: 서비스 자신의 어댑터 leaf가 이 leaf를 `implementation`으로 받는다. 절차는 - `docs/mongodb/consumer-leaf-guide.md`다. 작동하는 예(문서, mapper, repository, 포트 구현)는 시험 소스 패키지 - `…mongo.example`이고, `mongoStableContractTest`가 돌린다. -- `META-INF/spring.factories`로 등록한 `MongoDefaultsEnvironmentPostProcessor`가 `config/mongo.yml`을 가장 낮은 - 우선순위로 읽고, 명시한 `enabled=false`이면 Boot 4의 Mongo 자동 구성(Boot 자신의 등록 파일에서 읽는다)을 - `spring.autoconfigure.exclude`에 붙인다. -- surface는 두 가지다. 자동 구성 bean(README.md 「자동 구성」에 적힌 것)은 `enabled=true`로 켜진다. 나머지는 모두 - **라이브러리 API**다(README.md 「라이브러리 API」): 서비스 자신의 어댑터 leaf가 이 leaf를 `implementation`으로 - 받아 타입을 만든다. 라이브러리 API는 bean으로 등록하지 않고 자기 속성이 없다. -- Mongo health 연동은 leaf가 가진다. MongoRootAutoConfiguration이 내부 MongoPlatformHealthConfiguration을 import하고, - 그것이 MongoPlatformHealthIndicator를 안정된 bean 이름 mongoPlatformHealthContributor 아래 Boot의 HealthIndicator - SPI에 맞춘다. 바깥 endpoint 노출은 여전히 애플리케이션 Actuator 노출 정책이 정한다. - -## 허용 - -- 프로젝트 의존 둘. `Sha256`과 `HmacSha256` 도우미를 위한 `shared-contract`(테넌트 관찰 키, admin 명령 digest, - credential fingerprint, keyset cursor tag. `MongoDigestOutputTest`가 출력을 고정한다). `SecretSourcePort`만을 위한 - `application-core`. registry 항목의 `allowed_dependencies`는 `["application-core", "shared-contract"]`이고 빌드가 - 실제로 쓰는 것과 맞는다. `MongoProfileClientSettingsAutoConfiguration`의 bridge가 typed profile의 `uri-secret`을 - 배포가 설정한 비밀 값 backend로 해석한다. `verifyCleanArchitectureDependencies`는 해석된 edge가 선언된 것의 - 부분집합인지만 보므로 쓰지 않는 허가는 매번 통과한다. `MongoRegistryPermissionParityTest`가 반대 방향을 보고 두 - 집합이 다르면 실패한다. -- 서비스는 `app-bootstrap/build.gradle`에서 주석 처리한 한 줄 - `runtimeOnly project(':adapter:outbound:persistence-mongo')`로 이 leaf를 고른다. 기본 조립은 싣지 않는다. leaf는 - imperative만이다: reactive 쌍둥이(`reactive/**`, reactive 트랜잭션·세션), change-stream 소비자, change-stream → - 메시징 bridge는 2026-09-25에 지웠다(`docs/capability-status.md`). 그래서 leaf는 reactive starter도 - reactive-streams driver도 싣지 않는다(`MongoReactiveDriverAbsenceTest`). -- 외부 의존: (sync) Mongo starter, spring-boot-autoconfigure, spring-boot-health, micrometer-core, slf4j-api, - configuration processor. Boot Health가 Jackson 애너테이션을 싣지만 런타임 JSON 직렬화는 애플리케이션의 몫이라서 - Jackson 애너테이션은 compile 전용이다. 버전은 공용 Spring Boot BOM에서 온다. driver 버전을 직접 고정하지 않는다. -- 시험 전용: ArchUnit, Testcontainers(`mongodb`, `toxiproxy`). - -## 금지 (Forbidden) - -- inbound 어댑터, 이웃 outbound 어댑터, `app-bootstrap`(ArchUnit `OUTBOUND_ADAPTERS_*` 규칙 묶음). -- 운영 코드에 자리표시용 `Example*` 문서, repository, record, 어댑터 타입을 싣기. -- 따로 승인된 계약 없이 Mongo 위에 멱등성·outbox·lock을 더하기. -- 줄 안에 완전한 이름으로 쓴 타입 참조, 파일 하나에 공개 최상위 타입 둘 이상. - -### 패키지 경계 규칙 (`MongoModuleBoundaryTest`) - -설계의 모듈 의존 표를 그대로 옮긴 것이다. 하나라도 어기면 빌드가 실패한다: - -- `…mongo.api..`는 Spring, MongoDB driver, BSON, Reactor를 import하지 않는다. 프레임워크 없는 핵심 계약이다. - `api/package-info.java`가 이유를 적는다. -- Stable 패키지는 `…mongo.advanced..`에 의존하지 않는다. -- 운영 패키지는 `…mongo.testkit..`에 의존하지 않는다. -- `query` ↛ `aggregation`, `schema` ↛ 실행 패키지, `observation` ↛ 실행 패키지, `migration` ↛ `migration.flamingock`. - -### 일관성에 묶인 template - -`MongoConsistencyBinder`는 일관성 profile마다 `MongoTemplate`을 하나 끌어낸다. Spring Data는 template의 지원 계약에 -setter만 내놓고 getter를 내놓지 않는다. 그래서 따라가야 하는 부분 — write-concern resolver, 쓰기 결과 검사, -lifecycle 이벤트, entity callback과 auditing을 주는 `ApplicationContext` — 을 `MongoTemplateSupportContract`로 명시해 -넘긴다. 여기서 private 필드에 대한 리플렉션은 금지다. context 밖에서 프로그램으로 callback을 등록한 template은 -묶인 경로로 다시 만들 수 없다. 그 설정은 소리 없이 버리지 않고 지원하지 않는 것으로 둔다. - -### 공개 surface - -jar 하나 안의 모든 공개 최상위 타입이므로, `public`은 어느 패키지에 있든 모든 채택자에게 공개다. -`verifyMongoApiSurface`(`check` 안)가 surface를 개수를 담은 `docs/architecture/mongo-api-surface.txt`와 비교한다. -늘리려면 `updateMongoApiSurface -PapproveMongoApiSurfaceChange`가 필요하고, 그것은 리뷰 결정이다. - -아키텍처 규칙 catalog(`…mongo.architecture`)는 운영이 아니라 **testkit** source set에 있다: ArchUnit 입력이고, 그것을 -싣으면 모든 쓰는 쪽의 runtime classpath에 규칙 글이 올라갔다. 같은 이유로 릴리스 gate도 testkit 전용이고, 구현은 -둘이 아니라 하나다: `…mongo.testkit.release`가 lane이 쓴 JUnit XML을 읽고, `scripts/verify-mongodb-platform.sh`와 -`src/adapter/outbound/persistence-mongo/release/release-contracts.json`이 그것을 돌린다. 운영 classpath에 있던 두 번째 -짝 — 손으로 만든 category 이름 집합과 그것을 검사한 gate — 은 자기 시험 말고는 호출자가 없었고 category 뒤에 정본도 -없었다. 옮기지 않고 없앴다. - -아직 남았고, 리뷰 정리의 일부로 일부러 하지 않은 것: 구현 패키지를 `internal` 루트 아래로 옮기고 그 안의 가시성을 -낮추는 일. 약 200개 파일에 걸친 기계적 변경이라 자기 커밋에 둔다. 그 뒤에는 위 snapshot이 surface가 실제로 -줄었다는 증거가 된다. - -### credential과 운영 profile - -운영 `MongoProfileProperties`는 TLS, 인증, 엄격한 Stable API, standalone이 아닌 topology, 유한한 양의 timeout을 -선언해야 한다. `validate()`가 그것을 모두 강제한다. URI는 `secret://` 참조이고, 그것을 connection string으로 바꾸는 -것은 `MongoCredentialResolver`뿐이다 — 값을 호출자가 준 함수에 넘기고 돌려주지 않으니, credential은 필드나 bean -속성이나 로그 줄이 아니라 호출 한 번의 지역 변수다. - -`platform.profiles`가 비어 있지 않으면 채택은 일부러 실패하면 닫힌다. 조립 변경 하나에서 데이터 plane -`MongoCredentialResolver`와 함께 `MongoTopologyProbe`, `MongoSecurityProfile`, admin `MongoCredentialReference`, -`MongoSchemaVersionRange`를 준다. README.md에 필드 14개짜리 운영 profile 예가 다 있다. profile을 조금씩 주며 그 -요구를 기동 실패 하나씩으로 알아내는 것은 받아들인 채택 길이 아니다. - -기본 resolver는 `SecretSourcePort` 위의 bridge다(`MongoCredentialResolver.fromSecretSource`. 그 포트에 bean이 있고 -다른 resolver가 없을 때 등록한다). 키는 Redis·HTTP client 모듈처럼 참조의 마지막 경로 조각이다. 싣지 않은 것: -실제 인증서를 가진 container가 필요한 TLS lane(믿는 CA, 틀린 CA, hostname 불일치, 만료된 인증서). 교체 순서 — 새 -generation 준비, traffic 전환, 옛 lease 비우기, 닫기 — 는 `MongoClientGenerationConcurrencyTest`가 덮는다. - -### 문체가 아닌 플랫폼 불변식 - -- 트랜잭션 본문 재시도와 커밋 재시도는 **따로 도는 반복문**이다: 본문 시도마다 새 세션, 모르는 커밋에는 커밋만 - 재시도. 커밋이 모호해진 뒤에는 본문을 다시 돌리지 않는다(`MongoTransactionRetryCoordinator`, ADR-MONGO-003). -- `MongoExecutionOutcome`의 모호한 값 둘을 성공이나 실패로 뭉개면 안 된다. -- BSON 표현은 라이브러리 기본값이 아니라 `MongoTypeRepresentationManifest`에서 온다(ADR-MONGO-002). -- index와 validator 변경은 manifest와 admin plane을 거친다. 모든 drop은 소유권이 막는다(ADR-MONGO-004). -- 모든 구체 Advanced 타입은 `@MongoAdvancedEntryPoint(capability)`나 `@MongoAdvancedPolicy`를 단다. entry point는 - `MongoAdvancedCapabilityGuard`를 받고, 존재하기 전에 `require`를 부른다. `MongoAdvancedRules`가 두 절반을 강제한다. - 「실행되는 것은 막는다」가 「누가 기억해 낸 것은 막는다」가 되지 않게 하는 것이 분류 규칙이다. -- flag에는 설정 속성이 없다. Advanced 타입은 라이브러리 API다: 채택자의 어댑터가 코드로 - `MongoAdvancedCapabilityFlags`와 guard를 만든다. Stable 자동 구성은 `..advanced..` 아래의 어떤 것도 참조하면 안 - 된다. -- 이 leaf가 바인딩하는 모든 설정 키는 동작을 바꿔야 한다. 아무것도 읽지 않는 키나, 효과가 기동 실패뿐인 키는 - 문서로 남기지 않고 지운다(AGENTS.md capability 규칙 3). `docs/capability-status.md`가 무엇을 왜 지웠는지 적는다. -- 인터페이스는 이 leaf 안에 구현이 있을 때만 싣는다. Search, vector, time series, GridFS는 계약만 있었고 - 2026-09-25에 지웠다. -- observation tag는 `MongoObservationConvention`의 허용 목록으로 제한한다. - -## 테스트 - -`MongoCapabilityActivationTest`는 실제 `SpringApplication`을 띄워 있음 = 켜짐, 명시한 `enabled=false` = client· -template·플랫폼 bean 없음(Boot의 Mongo 자동 구성 포함)을 증명한다. `MongoPersistenceConfigTest`는 타입 있는 켜기 -바인딩과, 네트워크 연결 없이 mock `MongoClient`와 실제 `MongoTemplate`으로 켜진 기반을 덮는다. - -밀폐된 계약 시험은 `@Tag("mongodb-contract")`를 달고 `check`가 의존하는 `mongoStableContractTest`에서 돈다. container -lane은 `mongodb-replicaset` / `mongodb-failover`를 달고 자기 태스크에서만 돈다. 기본 `test` 태스크는 그것을 뺀다. -`check` 안에 Docker가 필요한 lane이 있으면 사람들이 `check`를 건너뛰게 되기 때문이다. - -```bash -cd src -./gradlew :adapter:outbound:persistence-mongo:check --console=plain -``` - -릴리스 gate는 저장소 루트에서 돈다: `scripts/verify-mongodb-platform.sh`(Stable)와 -`scripts/verify-mongodb-advanced.sh`(Advanced). +@AGENTS.md diff --git a/src/adapter/outbound/persistence-mongo/src/test/java/dev/caskeleton/adapter/outbound/mongo/MongoNamespaceContractTest.java b/src/adapter/outbound/persistence-mongo/src/test/java/dev/caskeleton/adapter/outbound/mongo/MongoNamespaceContractTest.java index 621b0e2e..cea76ec8 100644 --- a/src/adapter/outbound/persistence-mongo/src/test/java/dev/caskeleton/adapter/outbound/mongo/MongoNamespaceContractTest.java +++ b/src/adapter/outbound/persistence-mongo/src/test/java/dev/caskeleton/adapter/outbound/mongo/MongoNamespaceContractTest.java @@ -55,7 +55,7 @@ class MongoNamespaceContractTest { @DisplayName("operator-facing Mongo documentation names only the Boot 4 canonical namespace") void operatorDocumentationDoesNotRecommendTheDeprecatedNamespace() { Path module = repositoryRoot().resolve("src/adapter/outbound/persistence-mongo"); - List documents = List.of(module.resolve("README.md"), module.resolve("CLAUDE.md")); + List documents = List.of(module.resolve("README.md"), module.resolve("AGENTS.md")); assertThat(documents) .allSatisfy(path -> assertThat(Files.isRegularFile(path)).as(path.toString()).isTrue()); diff --git a/src/adapter/outbound/persistence-notification/AGENTS.md b/src/adapter/outbound/persistence-notification/AGENTS.md new file mode 100644 index 00000000..9a34f725 --- /dev/null +++ b/src/adapter/outbound/persistence-notification/AGENTS.md @@ -0,0 +1,52 @@ +# adapter:outbound:persistence-notification — 알림 관계형 영속 + +## 등록 정보 + +- 모듈 ID: `adapter-outbound-persistence-notification`. Gradle 경로와 허용 edge는 + `src/config/architecture/modules.json`에 있다. +- 이 모듈만 시험: `./gradlew :adapter:outbound:persistence-notification:test --console=plain`. +- 패키지 루트: `dev.caskeleton.adapter.outbound.persistence.notification`. 패키지 규칙은 + `persistence-fileserver`와 같아서 두 capability leaf를 같은 방식으로 읽는다: + - `platform.entity` — JPA 행만. + - `platform.repository` — Spring Data 인터페이스와 그것이 돌리는 SQL 글(`RecipientClaimSql`). + - `platform` — store 어댑터(`Jpa*`, `Jdbc*`, inbox의 `JpaNotificationInbox`와 그 outbox 도우미), + `NotificationRecordMapper`, payload codec. + - `configuration` — store를 bean으로 등록하는 자동 구성 창구. leaf 루트에는 scan 설정과 schema stream이 있다. + 엔티티 생성자·접근자·변경자는 store가 다른 패키지에서 쓰니 public이다. 엔티티는 leaf를 떠나지 않는다(포트는 + record를 싣는다). 가시성이 더는 그것을 말해 주지 않으므로 규칙이 말한다: + `JpaArchitectureRules.entitiesAreUsedOnlyInsideTheirLeaf`를 `JpaProductionArchitectureTest`(app-bootstrap + `architectureTest`)가 운영 그래프에 대고 이 leaf와 `persistence-fileserver`에 돌린다. + +## 시험은 어디 있나 + +| 무엇 | 어디 | 돌리기 | +|---|---|---| +| 단위·배선 시험 | 이 leaf, `src/test` | `:adapter:outbound:persistence-notification:test` | +| 이 store들의 실제 PostgreSQL 시험 | `persistence-jpa`, `src/postgresqlIntegrationTest/.../persistence/notification`(그 lane이 container와 Flyway 배선을 가진다) | `:adapter:outbound:persistence-jpa:postgresqlIntegrationTest --tests ''` | +| store가 통과해야 하는 포트 계약 | `application-notification` testFixtures, `*.testkit.*Contract`(preference, suppression, deduplication, request, reconciliation job, admin operation, template registry, recipient lease, recipient delivery, delivery attempt, attempt resolver, delivery projection, provider event ledger, contact point, 그리고 contact point·suppression store 위의 부수 효과) | 메모리 fake(`application-notification` 시험)와 `persistence-jpa`의 `PostgreSql*ContractTest`가 모두 계약을 상속한다. PostgreSQL 쪽은 `jpaPlatformContractTest`가 돌린다 | +| migration 고정 | `persistence-jpa/src/test/resources/db/applied-migrations.sha256` | `:adapter:outbound:persistence-jpa:test`의 `AppliedMigrationImmutabilityTest` | + +`application-notification` testFixtures에 계약이 있는 포트의 store는 따로 손으로 쓴 PostgreSQL 시험이 아니라 +그 계약의 PostgreSQL 하위 클래스로 시험한다. vendor에 관한 경우(CHECK 제약, bulk update의 `@Version`)는 하위 +클래스에 남긴다. 계약이 없는 포트(serving-state 읽기 모델, 동의, inbox)와 그 이유는 +`docs/testing/TESTING_STRATEGY.md` 9.2절에 있다. + +## 규칙 + +- **모든 쓰기는 호출자의 트랜잭션에 합류한다.** store 쓰기는 `CallerTransaction.require("")`로 + 시작한다. 트랜잭션은 유스케이스가 가진다(소유자 결정 2026-09-25). +- **migration**은 `src/main/resources/db/migration/jpa/notification-platform`에 있고 자기 Flyway stream + (`NotificationSchemaStream`, history 테이블 `flyway_jpa_notification_history`)으로 돈다. 적용한 파일은 고치지 + 않는다: 다음 `V__`를 더하고, 그 SHA-256을 `applied-migrations.sha256`에 고정하고, + `NotificationFixtures.migrations()`에 더한다. 행을 지우는 migration은 어떤 행이 남고 왜인지 SQL 주석에 + 적는다. 이미 있는 테이블을 잠그는 migration은 `SET LOCAL lock_timeout = '5s';`로 시작한다 + (`docs/jpa/migration-guide.md` "Bound the lock wait". persistence-jpa의 `MigrationLockWaitTest`가 그것이 없는 + migration을 거절한다). +- **insert냐 update냐는 데이터베이스가 정한다.** 찾은 뒤 insert하지 않는다: `ON CONFLICT () DO + NOTHING`으로 insert하고, 아무것도 insert하지 않았으면 관리되는 엔티티로 있는 행을 update한다 + (`JpaSuppressionStore.upsert`, `JpaPolicyStores.Preferences.save`, `DeduplicationClaims.insertOrFind`). 충돌 + 대상에는 migration에 unique 제약이 있어야 한다. +- **`@Version` 테이블의 bulk·native `UPDATE`는 version을 올린다**(`version = version + 1`). 호출자가 그 행을 다시 + 읽을 수 있으면 `@Modifying(clearAutomatically = true, flushAutomatically = true)`다. version 부분은 + `JpaVersionedBulkUpdateRule`(persistence-jpa testFixtures)이 `:app-bootstrap:architectureTest`에서 강제한다. +- repository는 `CrudRepository`가 아니라 `Repository`를 상속하고, 테넌트 범위의 finder만 내놓는다. diff --git a/src/adapter/outbound/persistence-notification/CLAUDE.md b/src/adapter/outbound/persistence-notification/CLAUDE.md index 9a34f725..43c994c2 100644 --- a/src/adapter/outbound/persistence-notification/CLAUDE.md +++ b/src/adapter/outbound/persistence-notification/CLAUDE.md @@ -1,52 +1 @@ -# adapter:outbound:persistence-notification — 알림 관계형 영속 - -## 등록 정보 - -- 모듈 ID: `adapter-outbound-persistence-notification`. Gradle 경로와 허용 edge는 - `src/config/architecture/modules.json`에 있다. -- 이 모듈만 시험: `./gradlew :adapter:outbound:persistence-notification:test --console=plain`. -- 패키지 루트: `dev.caskeleton.adapter.outbound.persistence.notification`. 패키지 규칙은 - `persistence-fileserver`와 같아서 두 capability leaf를 같은 방식으로 읽는다: - - `platform.entity` — JPA 행만. - - `platform.repository` — Spring Data 인터페이스와 그것이 돌리는 SQL 글(`RecipientClaimSql`). - - `platform` — store 어댑터(`Jpa*`, `Jdbc*`, inbox의 `JpaNotificationInbox`와 그 outbox 도우미), - `NotificationRecordMapper`, payload codec. - - `configuration` — store를 bean으로 등록하는 자동 구성 창구. leaf 루트에는 scan 설정과 schema stream이 있다. - 엔티티 생성자·접근자·변경자는 store가 다른 패키지에서 쓰니 public이다. 엔티티는 leaf를 떠나지 않는다(포트는 - record를 싣는다). 가시성이 더는 그것을 말해 주지 않으므로 규칙이 말한다: - `JpaArchitectureRules.entitiesAreUsedOnlyInsideTheirLeaf`를 `JpaProductionArchitectureTest`(app-bootstrap - `architectureTest`)가 운영 그래프에 대고 이 leaf와 `persistence-fileserver`에 돌린다. - -## 시험은 어디 있나 - -| 무엇 | 어디 | 돌리기 | -|---|---|---| -| 단위·배선 시험 | 이 leaf, `src/test` | `:adapter:outbound:persistence-notification:test` | -| 이 store들의 실제 PostgreSQL 시험 | `persistence-jpa`, `src/postgresqlIntegrationTest/.../persistence/notification`(그 lane이 container와 Flyway 배선을 가진다) | `:adapter:outbound:persistence-jpa:postgresqlIntegrationTest --tests ''` | -| store가 통과해야 하는 포트 계약 | `application-notification` testFixtures, `*.testkit.*Contract`(preference, suppression, deduplication, request, reconciliation job, admin operation, template registry, recipient lease, recipient delivery, delivery attempt, attempt resolver, delivery projection, provider event ledger, contact point, 그리고 contact point·suppression store 위의 부수 효과) | 메모리 fake(`application-notification` 시험)와 `persistence-jpa`의 `PostgreSql*ContractTest`가 모두 계약을 상속한다. PostgreSQL 쪽은 `jpaPlatformContractTest`가 돌린다 | -| migration 고정 | `persistence-jpa/src/test/resources/db/applied-migrations.sha256` | `:adapter:outbound:persistence-jpa:test`의 `AppliedMigrationImmutabilityTest` | - -`application-notification` testFixtures에 계약이 있는 포트의 store는 따로 손으로 쓴 PostgreSQL 시험이 아니라 -그 계약의 PostgreSQL 하위 클래스로 시험한다. vendor에 관한 경우(CHECK 제약, bulk update의 `@Version`)는 하위 -클래스에 남긴다. 계약이 없는 포트(serving-state 읽기 모델, 동의, inbox)와 그 이유는 -`docs/testing/TESTING_STRATEGY.md` 9.2절에 있다. - -## 규칙 - -- **모든 쓰기는 호출자의 트랜잭션에 합류한다.** store 쓰기는 `CallerTransaction.require("")`로 - 시작한다. 트랜잭션은 유스케이스가 가진다(소유자 결정 2026-09-25). -- **migration**은 `src/main/resources/db/migration/jpa/notification-platform`에 있고 자기 Flyway stream - (`NotificationSchemaStream`, history 테이블 `flyway_jpa_notification_history`)으로 돈다. 적용한 파일은 고치지 - 않는다: 다음 `V__`를 더하고, 그 SHA-256을 `applied-migrations.sha256`에 고정하고, - `NotificationFixtures.migrations()`에 더한다. 행을 지우는 migration은 어떤 행이 남고 왜인지 SQL 주석에 - 적는다. 이미 있는 테이블을 잠그는 migration은 `SET LOCAL lock_timeout = '5s';`로 시작한다 - (`docs/jpa/migration-guide.md` "Bound the lock wait". persistence-jpa의 `MigrationLockWaitTest`가 그것이 없는 - migration을 거절한다). -- **insert냐 update냐는 데이터베이스가 정한다.** 찾은 뒤 insert하지 않는다: `ON CONFLICT () DO - NOTHING`으로 insert하고, 아무것도 insert하지 않았으면 관리되는 엔티티로 있는 행을 update한다 - (`JpaSuppressionStore.upsert`, `JpaPolicyStores.Preferences.save`, `DeduplicationClaims.insertOrFind`). 충돌 - 대상에는 migration에 unique 제약이 있어야 한다. -- **`@Version` 테이블의 bulk·native `UPDATE`는 version을 올린다**(`version = version + 1`). 호출자가 그 행을 다시 - 읽을 수 있으면 `@Modifying(clearAutomatically = true, flushAutomatically = true)`다. version 부분은 - `JpaVersionedBulkUpdateRule`(persistence-jpa testFixtures)이 `:app-bootstrap:architectureTest`에서 강제한다. -- repository는 `CrudRepository`가 아니라 `Repository`를 상속하고, 테넌트 범위의 finder만 내놓는다. +@AGENTS.md diff --git a/src/adapter/outbound/redis-sdk/README.md b/src/adapter/outbound/redis-sdk/README.md index 84ff69be..f5142640 100644 --- a/src/adapter/outbound/redis-sdk/README.md +++ b/src/adapter/outbound/redis-sdk/README.md @@ -73,7 +73,7 @@ executor, operations). 등록된 script(`RedisScriptRegistry`). 서비스가 SDK를 조립하는 곳에서 넘긴다. 패키지 규칙(driver 가두기, 문자열 명령 surface 없음, 트랜잭션과 raw gateway의 불변식)은 -`src/adapter/outbound/cache-redis/CLAUDE.md`의 「Redis 런타임과 골라 쓰는 typed SDK」에 있다. +`src/adapter/outbound/cache-redis/AGENTS.md`의 「Redis 런타임과 골라 쓰는 typed SDK」에 있다. `RedisSdkModuleBoundaryTest`가 강제한다. ## env 키 diff --git a/src/adapter/outbound/support/AGENTS.md b/src/adapter/outbound/support/AGENTS.md new file mode 100644 index 00000000..a68269c7 --- /dev/null +++ b/src/adapter/outbound/support/AGENTS.md @@ -0,0 +1,42 @@ +# adapter:outbound:support — outbound 공용 지원 + +## 등록 정보 + +- 모듈 ID: `adapter-outbound-support` +- Gradle 경로: `:adapter:outbound:support` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:support:test --console=plain` +- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. +- registry 정본: `src/config/architecture/modules.json`. + +패키지 루트: `dev.caskeleton.adapter.outbound`와 `dev.caskeleton.adapter.outbound.support`. + +## 책임 + +- 다시 쓰는 outbound correlation, fail-open 의존성 로그, 자동 구성 이음매를 가진다. +- 등록된 messaging·cache·notification·httpclient leaf가 쓰는 기술 지원을 준다. +- 템플릿의 `IntegrationEventEncoderPort`(`messaging/JsonIntegrationEventEncoder`)를 가진다. + `IntegrationEventEncoderAutoConfiguration`이 모든 contract contribution bean 위에 등록하고, 서비스 자신의 + 인코더가 있으면 물러선다. 여기 있는 이유는 유스케이스가 outbox에 append하기 전에 인코딩하는데, 메시징 모듈을 + 싣지 않는 조립도 있기 때문이다. 이것은 외부 시스템 프로토콜이 아니라 애플리케이션 자신의 envelope v1 + 형식이다. +- 디렉터리 descriptor 기준의 로컬 파일 시스템 기본 장치(`filesystem/SecureDirectoryWalk`, + `filesystem/SecureFileAccess`)를 가진다: root 아래에서 디렉터리 descriptor를 하나씩 따라가며 + `NOFOLLOW_LINKS`로 열기, 만들기, 지우기, stat, 옮기기를 하고, symbolic 경로 요소와 바깥으로 나가기를 타입 있는 + `IOException`으로 거절한다. 저장 capability가 그것을 자기 실패 어휘로 바꾼다(파일 서버의 + `LocalStorageFailures`). 여기는 오류 코드를 모른다. +- 유일한 엄격 설정 바인딩 `StrictSettingsBinder`를 가진다. inbound leaf가 쓸 수 있는 유일한 support + 클래스이기도 하다: `adapter:inbound:web`이 이것으로 `app.security`를 바인딩한다(registry edge와 클래스 이름을 + 댄 ArchUnit 예외, 2026-11-01부터). 타입에 있는 설정의 빈 값(`APP_FILESERVER_PLATFORM_QUOTA_NAMESPACE_LIMIT=`)은 + 설정 안 함으로 바인딩한다. 타입에 없는 이름 아래의 빈 값은 계속 거절한다(2026-11-03에 정함). +- 기능 전용 client와 라우팅 정책은 그것을 가진 leaf에 둔다. + +## 경계 + +- 허용 프로젝트 의존은 registry가 가진다: application, domain, shared 계약. +- inbound 전송, 영속, bootstrap, 샘플 의존이 없다. +- 업무 규칙이나 특정 외부 시스템 프로토콜 구현이 없다. + +## 테스트 + +지원 동작은 이 모듈만 보는 단위 시험으로 본다. 시험할 계약이 설정 배선 자체가 아니면 Spring application +context를 띄우지 않는다. diff --git a/src/adapter/outbound/support/CLAUDE.md b/src/adapter/outbound/support/CLAUDE.md index a68269c7..43c994c2 100644 --- a/src/adapter/outbound/support/CLAUDE.md +++ b/src/adapter/outbound/support/CLAUDE.md @@ -1,42 +1 @@ -# adapter:outbound:support — outbound 공용 지원 - -## 등록 정보 - -- 모듈 ID: `adapter-outbound-support` -- Gradle 경로: `:adapter:outbound:support` -- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:support:test --console=plain` -- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. -- registry 정본: `src/config/architecture/modules.json`. - -패키지 루트: `dev.caskeleton.adapter.outbound`와 `dev.caskeleton.adapter.outbound.support`. - -## 책임 - -- 다시 쓰는 outbound correlation, fail-open 의존성 로그, 자동 구성 이음매를 가진다. -- 등록된 messaging·cache·notification·httpclient leaf가 쓰는 기술 지원을 준다. -- 템플릿의 `IntegrationEventEncoderPort`(`messaging/JsonIntegrationEventEncoder`)를 가진다. - `IntegrationEventEncoderAutoConfiguration`이 모든 contract contribution bean 위에 등록하고, 서비스 자신의 - 인코더가 있으면 물러선다. 여기 있는 이유는 유스케이스가 outbox에 append하기 전에 인코딩하는데, 메시징 모듈을 - 싣지 않는 조립도 있기 때문이다. 이것은 외부 시스템 프로토콜이 아니라 애플리케이션 자신의 envelope v1 - 형식이다. -- 디렉터리 descriptor 기준의 로컬 파일 시스템 기본 장치(`filesystem/SecureDirectoryWalk`, - `filesystem/SecureFileAccess`)를 가진다: root 아래에서 디렉터리 descriptor를 하나씩 따라가며 - `NOFOLLOW_LINKS`로 열기, 만들기, 지우기, stat, 옮기기를 하고, symbolic 경로 요소와 바깥으로 나가기를 타입 있는 - `IOException`으로 거절한다. 저장 capability가 그것을 자기 실패 어휘로 바꾼다(파일 서버의 - `LocalStorageFailures`). 여기는 오류 코드를 모른다. -- 유일한 엄격 설정 바인딩 `StrictSettingsBinder`를 가진다. inbound leaf가 쓸 수 있는 유일한 support - 클래스이기도 하다: `adapter:inbound:web`이 이것으로 `app.security`를 바인딩한다(registry edge와 클래스 이름을 - 댄 ArchUnit 예외, 2026-11-01부터). 타입에 있는 설정의 빈 값(`APP_FILESERVER_PLATFORM_QUOTA_NAMESPACE_LIMIT=`)은 - 설정 안 함으로 바인딩한다. 타입에 없는 이름 아래의 빈 값은 계속 거절한다(2026-11-03에 정함). -- 기능 전용 client와 라우팅 정책은 그것을 가진 leaf에 둔다. - -## 경계 - -- 허용 프로젝트 의존은 registry가 가진다: application, domain, shared 계약. -- inbound 전송, 영속, bootstrap, 샘플 의존이 없다. -- 업무 규칙이나 특정 외부 시스템 프로토콜 구현이 없다. - -## 테스트 - -지원 동작은 이 모듈만 보는 단위 시험으로 본다. 시험할 계약이 설정 배선 자체가 아니면 Spring application -context를 띄우지 않는다. +@AGENTS.md diff --git a/src/adapter/outbound/support/README.md b/src/adapter/outbound/support/README.md index bf801a7c..c4b782e2 100644 --- a/src/adapter/outbound/support/README.md +++ b/src/adapter/outbound/support/README.md @@ -6,7 +6,7 @@ 허용/금지 의존 정책은 `src/build.gradle` 의 `allowedProjectDependencies['adapter:outbound:support']` 항목이 SSOT 다(이 모듈은 아직 별도 -CLAUDE.md 를 두지 않았다). 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를 모아둔 참조용 +AGENTS.md 를 두지 않았다). 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를 모아둔 참조용 기록이다 — 코드를 읽다 "왜 이렇게 했나"가 궁금할 때 본다. ## 왜 별도 모듈인가 diff --git a/src/app-bootstrap/AGENTS.md b/src/app-bootstrap/AGENTS.md new file mode 100644 index 00000000..21ed43ce --- /dev/null +++ b/src/app-bootstrap/AGENTS.md @@ -0,0 +1,121 @@ +# app-bootstrap — 애플리케이션 진입점과 조립 루트 + +## 등록 정보 + +- 모듈 ID: `app-bootstrap` +- Gradle 경로: `:app-bootstrap` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :app-bootstrap:test --console=plain` +- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. +- registry 정본: `src/config/architecture/modules.json`. + +패키지 루트: `dev.caskeleton.bootstrap`. + +## 책임 + +- Spring Boot 진입점(`CaSkeletonApplication`). +- 런타임 설정과 로깅 시작. +- 모듈을 가로지르는 마지막 배선. +- 모든 모듈을 들여다보는 아키텍처 시험. + +## 허용 + +- 이 모듈의 Gradle 의존성이 분명히 선언하고 아키텍처 registry가 허용한 런타임 leaf. 해석된 Gradle + runtime 그래프가 런타임의 정본이다. 구성원 목록을 metadata에 다시 적지 않는다. +- Spring Boot 시작·런타임 의존성. +- 시험에서 ArchUnit. + +## 금지 + +- 구체적인 업무 정책. +- bootstrap 아래에 직접 쓴 controller, 유스케이스, repository 어댑터, mapper. +- 업무 로직을 구현하는 설정 클래스. +- `application-core`나 `domain-core` 포트를 구현하기. 포트를 구현하는 클래스는 의존성을 어떻게 + 설정했든 outbound 어댑터이고 `adapter/outbound/*` leaf에 둔다 — + `CompositionRootBoundaryArchitectureTest`가 예외 없이 강제한다. +- 기동 실패를 `throw new IllegalStateException(...)`으로 내기. `StartupFailures` + (`adapter:outbound:support`, 패키지 `support.startup`: `envValidation` / `profileMismatch` / + `requiredAdapterDisabled` / `migrationFailed`)를 써서 실패가 sysexits 종료 코드와 구조화된 로그 + 필드를 싣게 한다 — `StartupFailureContractArchitectureTest`가 강제한다. +- 「운영 환경인가?」를 이 모듈 안에서 답하기. 저장소 전체의 profile 어휘는 + `dev.caskeleton.shared.runtime.RuntimeEnvironment`가 가진다. +- `src/test`에서 `org.testcontainers`에 의존하기. 실제 서비스를 쓰는 시험은 `src/integrationTest`에 + 둔다. `docs/testing/TESTING_STRATEGY.md`를 본다. + +## 패키지 배치 + +아래 규칙은 그것이 없어서 이 모듈의 리뷰 대상이 된 어긋남이 생겼기 때문에 있다 +(`docs/reviews/2026-09-07-app-bootstrap-module-code-review.md`). capability의 절반은 `autoconfigure/` +아래, 절반은 패키지 루트에 있었다. `Settings` 클래스는 규칙 없이 `settings/` 패키지와 각 기능 +패키지에 나뉘어 있었다. 그리고 같은 분해 문제를 같은 leaf에서 두 가지로 풀었다 — Notification은 작은 +설정 아홉 개로, Redis는 376줄 클래스 하나로. + +- **capability의 조립은 그 capability 자신의 모듈에 있다.** 그 모듈의 `AutoConfiguration.imports`가 + 등록하고, 설정은 그 모듈의 `config/module-defaults/*.yml`에 둔다. JPA(기동 guard, Flyway 전략, + lock decorator, readiness, `JpaActivationEnvironmentPostProcessor`의 완전히 끄기 처리)는 + `adapter:outbound:persistence-jpa`, Redis(readiness)는 `adapter:outbound:cache-redis`, 알림은 + `composition:notification-platform`이다. 모든 capability는 `build.gradle`에서 주석 처리한 + `runtimeOnly` 한 줄이다. 기본 조립은 web, 관측, core들, support, identifier다. 이 leaf는 capability + 목록을 두지 않는다: 스위치 registry도, capability 사이 의존 검증기도, 켜기 endpoint도 없다. + component scan은 `dev.caskeleton.bootstrap`만 본다. web(`WebAdapterAutoConfiguration`, + `WebSecurityAutoConfiguration`, `WebMethodSecurityAutoConfiguration`)과 support + (`OutboundSupportConfig`)는 자기 `AutoConfiguration.imports`로 들어온다. `autoconfigure//`에 + 남는 것은 모든 애플리케이션에 필요한 애플리케이션 조립인 `common`(시계)뿐이다. outbox relay, + 멱등성 executor, durable operation(유스케이스와 `/operations` endpoint. 2026-11-01 성숙도 리뷰 뒤로 bootstrap 밖)은 + `composition:outbox-relay`, `composition:idempotency`, `composition:durable-operation`이다. 각각 + `runtimeOnly` 한 줄로 고르고, 자기 포트가 생기기 전에는 아무것도 만들지 않는다. capability의 + role → permission 대응은 `config/security.yml`이 아니라 그 capability의 `config/module-defaults` + 파일에 담긴다. 모든 조립 루트에 필요한 런타임 배선 — tracing, metric 계약 filter, domain-context + 전파, 사용자 principal 가명화(`PrivacySettings`), actuator chain — 은 `composition:service-runtime`이다. +- **`Settings`는 `settings/`가 아니라 그 capability 옆에 둔다.** `settings/` 패키지는 + 어느 capability에도 속하지 않는 설정 — `BootstrapSettings`, `RuntimeSafetySettings` — 만 담는다. + 이 설정은 `StrictSettingsBinder`로 엄격하게 바인딩하고 scan하지 않는다. 로깅에는 settings record가 + 없다. `logback-spring.xml`이 `app.logging.*`을 직접 읽고 `LoggingConfigurationRule`이 Logback이 쓸 + 수 없는 값을 거절한다. +- **`runtime/`은 애플리케이션 자체에 대한 guard를 담는다** — 비밀 값, 숫자 한계, 오류 상세 노출, + 여러 인스턴스 조율, runtime profile 검사(`RuntimeEnvironmentProfileValidator`). capability 설정에 + 대한 guard(JPA OSIV·DDL·pool·TLS·vendor guard, Mongo 연결 출처 규칙, GraphQL 배포 모드 규칙)는 그 + capability의 모듈과 함께 나간다. 그래야 capability가 있을 때만 정확히 존재한다. +- **기동 실패 어휘는 `adapter:outbound:support`에 있다**(`support.startup`: phase, 오류 코드, 예외, + `StartupFailures`, `StartupValidationContext`, `StartupOrder`, `ReadinessGroup`, `RuntimeWarnings`). + 그래서 capability 모듈은 이 leaf에 의존하지 않고 같은 방식으로 실패한다. `runtime/startup/`에는 + `StartupFailureExceptionReporter`만 남는다. +- **환경만 보는 guard는 `StartupRule` bean이다**(`support.startup`). 위반을 돌려주고, 유일한 + `StartupRuleRunner`가 다른 singleton이 생기기 전에 그것을 올린다(`Environment`, bean factory, 정적 + `RequiredProductionSecrets`의 `ObjectProvider`만 받는 `static` `@Bean` 메서드로 선언한다. 모든 + profile에서 runner는 어떤 규칙을 돌리기 전에 규칙마다, 그리고 `RequiredProductionSecrets`마다 하나씩 + 만든다. 그중 하나가 만드는 다른 bean이 있으면 그 이름을 대며 기동을 실패시킨다. runtime 클래스에 + `@Value`/`@Autowired`/`@Inject`/`@Resource` 멤버, `@PostConstruct`/`@PreDestroy` 콜백, + `@ConfigurationProperties` 바인딩이 있는 것도 이름을 대며 실패시킨다 — 그런 것은 post-processor보다 + 먼저 만들어져 값이 비어 있게 된다). 다른 bean이 필요한 guard는 bean으로 남는다. capability의 운영 + 비밀 값은 그 capability의 것이다: 그 모듈이 `RequiredProductionSecrets` bean을 내놓고, + `SecretSourceValidator`는 어떤 role이 있는지 모르는 채로 이름을 검사한다. + +## 분해 기준 + +취향에 맡기지 않고 적어 둔다. 「충분히 길다고 느꼈다」가 같은 질문에 두 가지 답을 낳았기 때문이다. + +- `@Configuration` 하나는 조립 관심사 하나를 담는다. 대략 **`@Bean` 메서드 여덟 개**를 넘거나, 서로 + 관계없는 포트 묶음 둘을 조립하게 되면 — 둘 중 먼저 오는 때에 — 나눈다. +- `@ConfigurationProperties` 클래스 하나는 capability namespace 하나를 가진다. +- 설정이 둘 이상 필요한 capability는 루트 클래스를 둔다. 루트가 `enabled` 조건, + `@EnableConfigurationProperties`, 관심사별 클래스의 `@Import`를 가진다. 아무것도 scan하지 않는다: + 조건이 걸린 루트에서 `@Import`해야 `enabled=false`가 권고가 아니라 실제로 끄는 스위치가 된다. + `cache-redis`의 `capability/RedisCapabilityConfig`가 참조 예다. 다시 쓸 Spring 조립을 가진 optional + 어댑터 capability는 자기 루트를 내놓는다. 알림은 `adapter:outbound:notification`의 + `NotificationPlatformAutoConfiguration`과 `composition:notification-platform`의 + `NotificationApplicationCompositionAutoConfiguration`을 쓴다. JPA는 + `adapter:outbound:persistence-jpa`의 package-private `PersistenceJpaAutoConfiguration`, + `PersistenceJpaRuntimeConfig`, `startup.JpaStartupAutoConfiguration`을 쓰고, 이 모듈은 기본 조립에 + 없다(`build.gradle`의 `// runtimeOnly project(':adapter:outbound:persistence-jpa')`). + Mongo도 같은 규칙을 따른다: persistence-mongo leaf가 MongoRootAutoConfiguration과 그 내부 health + bridge를 가지고, bootstrap은 Mongo 전용 운영 health 설정을 가지지 않는다. +- 나눈 capability의 공용 도우미는 `*Util` 바구니가 아니라 하는 일을 이름으로 단 자기 타입을 가진다 — + `cache-redis`의 `capability/RedisKeys`가 참조 예다. + +## 테스트 + +```bash +cd src +./gradlew :app-bootstrap:test +./gradlew verifyCleanArchitectureDependencies +``` diff --git a/src/app-bootstrap/CLAUDE.md b/src/app-bootstrap/CLAUDE.md index 21ed43ce..43c994c2 100644 --- a/src/app-bootstrap/CLAUDE.md +++ b/src/app-bootstrap/CLAUDE.md @@ -1,121 +1 @@ -# app-bootstrap — 애플리케이션 진입점과 조립 루트 - -## 등록 정보 - -- 모듈 ID: `app-bootstrap` -- Gradle 경로: `:app-bootstrap` -- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :app-bootstrap:test --console=plain` -- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. -- registry 정본: `src/config/architecture/modules.json`. - -패키지 루트: `dev.caskeleton.bootstrap`. - -## 책임 - -- Spring Boot 진입점(`CaSkeletonApplication`). -- 런타임 설정과 로깅 시작. -- 모듈을 가로지르는 마지막 배선. -- 모든 모듈을 들여다보는 아키텍처 시험. - -## 허용 - -- 이 모듈의 Gradle 의존성이 분명히 선언하고 아키텍처 registry가 허용한 런타임 leaf. 해석된 Gradle - runtime 그래프가 런타임의 정본이다. 구성원 목록을 metadata에 다시 적지 않는다. -- Spring Boot 시작·런타임 의존성. -- 시험에서 ArchUnit. - -## 금지 - -- 구체적인 업무 정책. -- bootstrap 아래에 직접 쓴 controller, 유스케이스, repository 어댑터, mapper. -- 업무 로직을 구현하는 설정 클래스. -- `application-core`나 `domain-core` 포트를 구현하기. 포트를 구현하는 클래스는 의존성을 어떻게 - 설정했든 outbound 어댑터이고 `adapter/outbound/*` leaf에 둔다 — - `CompositionRootBoundaryArchitectureTest`가 예외 없이 강제한다. -- 기동 실패를 `throw new IllegalStateException(...)`으로 내기. `StartupFailures` - (`adapter:outbound:support`, 패키지 `support.startup`: `envValidation` / `profileMismatch` / - `requiredAdapterDisabled` / `migrationFailed`)를 써서 실패가 sysexits 종료 코드와 구조화된 로그 - 필드를 싣게 한다 — `StartupFailureContractArchitectureTest`가 강제한다. -- 「운영 환경인가?」를 이 모듈 안에서 답하기. 저장소 전체의 profile 어휘는 - `dev.caskeleton.shared.runtime.RuntimeEnvironment`가 가진다. -- `src/test`에서 `org.testcontainers`에 의존하기. 실제 서비스를 쓰는 시험은 `src/integrationTest`에 - 둔다. `docs/testing/TESTING_STRATEGY.md`를 본다. - -## 패키지 배치 - -아래 규칙은 그것이 없어서 이 모듈의 리뷰 대상이 된 어긋남이 생겼기 때문에 있다 -(`docs/reviews/2026-09-07-app-bootstrap-module-code-review.md`). capability의 절반은 `autoconfigure/` -아래, 절반은 패키지 루트에 있었다. `Settings` 클래스는 규칙 없이 `settings/` 패키지와 각 기능 -패키지에 나뉘어 있었다. 그리고 같은 분해 문제를 같은 leaf에서 두 가지로 풀었다 — Notification은 작은 -설정 아홉 개로, Redis는 376줄 클래스 하나로. - -- **capability의 조립은 그 capability 자신의 모듈에 있다.** 그 모듈의 `AutoConfiguration.imports`가 - 등록하고, 설정은 그 모듈의 `config/module-defaults/*.yml`에 둔다. JPA(기동 guard, Flyway 전략, - lock decorator, readiness, `JpaActivationEnvironmentPostProcessor`의 완전히 끄기 처리)는 - `adapter:outbound:persistence-jpa`, Redis(readiness)는 `adapter:outbound:cache-redis`, 알림은 - `composition:notification-platform`이다. 모든 capability는 `build.gradle`에서 주석 처리한 - `runtimeOnly` 한 줄이다. 기본 조립은 web, 관측, core들, support, identifier다. 이 leaf는 capability - 목록을 두지 않는다: 스위치 registry도, capability 사이 의존 검증기도, 켜기 endpoint도 없다. - component scan은 `dev.caskeleton.bootstrap`만 본다. web(`WebAdapterAutoConfiguration`, - `WebSecurityAutoConfiguration`, `WebMethodSecurityAutoConfiguration`)과 support - (`OutboundSupportConfig`)는 자기 `AutoConfiguration.imports`로 들어온다. `autoconfigure//`에 - 남는 것은 모든 애플리케이션에 필요한 애플리케이션 조립인 `common`(시계)뿐이다. outbox relay, - 멱등성 executor, durable operation(유스케이스와 `/operations` endpoint. 2026-11-01 성숙도 리뷰 뒤로 bootstrap 밖)은 - `composition:outbox-relay`, `composition:idempotency`, `composition:durable-operation`이다. 각각 - `runtimeOnly` 한 줄로 고르고, 자기 포트가 생기기 전에는 아무것도 만들지 않는다. capability의 - role → permission 대응은 `config/security.yml`이 아니라 그 capability의 `config/module-defaults` - 파일에 담긴다. 모든 조립 루트에 필요한 런타임 배선 — tracing, metric 계약 filter, domain-context - 전파, 사용자 principal 가명화(`PrivacySettings`), actuator chain — 은 `composition:service-runtime`이다. -- **`Settings`는 `settings/`가 아니라 그 capability 옆에 둔다.** `settings/` 패키지는 - 어느 capability에도 속하지 않는 설정 — `BootstrapSettings`, `RuntimeSafetySettings` — 만 담는다. - 이 설정은 `StrictSettingsBinder`로 엄격하게 바인딩하고 scan하지 않는다. 로깅에는 settings record가 - 없다. `logback-spring.xml`이 `app.logging.*`을 직접 읽고 `LoggingConfigurationRule`이 Logback이 쓸 - 수 없는 값을 거절한다. -- **`runtime/`은 애플리케이션 자체에 대한 guard를 담는다** — 비밀 값, 숫자 한계, 오류 상세 노출, - 여러 인스턴스 조율, runtime profile 검사(`RuntimeEnvironmentProfileValidator`). capability 설정에 - 대한 guard(JPA OSIV·DDL·pool·TLS·vendor guard, Mongo 연결 출처 규칙, GraphQL 배포 모드 규칙)는 그 - capability의 모듈과 함께 나간다. 그래야 capability가 있을 때만 정확히 존재한다. -- **기동 실패 어휘는 `adapter:outbound:support`에 있다**(`support.startup`: phase, 오류 코드, 예외, - `StartupFailures`, `StartupValidationContext`, `StartupOrder`, `ReadinessGroup`, `RuntimeWarnings`). - 그래서 capability 모듈은 이 leaf에 의존하지 않고 같은 방식으로 실패한다. `runtime/startup/`에는 - `StartupFailureExceptionReporter`만 남는다. -- **환경만 보는 guard는 `StartupRule` bean이다**(`support.startup`). 위반을 돌려주고, 유일한 - `StartupRuleRunner`가 다른 singleton이 생기기 전에 그것을 올린다(`Environment`, bean factory, 정적 - `RequiredProductionSecrets`의 `ObjectProvider`만 받는 `static` `@Bean` 메서드로 선언한다. 모든 - profile에서 runner는 어떤 규칙을 돌리기 전에 규칙마다, 그리고 `RequiredProductionSecrets`마다 하나씩 - 만든다. 그중 하나가 만드는 다른 bean이 있으면 그 이름을 대며 기동을 실패시킨다. runtime 클래스에 - `@Value`/`@Autowired`/`@Inject`/`@Resource` 멤버, `@PostConstruct`/`@PreDestroy` 콜백, - `@ConfigurationProperties` 바인딩이 있는 것도 이름을 대며 실패시킨다 — 그런 것은 post-processor보다 - 먼저 만들어져 값이 비어 있게 된다). 다른 bean이 필요한 guard는 bean으로 남는다. capability의 운영 - 비밀 값은 그 capability의 것이다: 그 모듈이 `RequiredProductionSecrets` bean을 내놓고, - `SecretSourceValidator`는 어떤 role이 있는지 모르는 채로 이름을 검사한다. - -## 분해 기준 - -취향에 맡기지 않고 적어 둔다. 「충분히 길다고 느꼈다」가 같은 질문에 두 가지 답을 낳았기 때문이다. - -- `@Configuration` 하나는 조립 관심사 하나를 담는다. 대략 **`@Bean` 메서드 여덟 개**를 넘거나, 서로 - 관계없는 포트 묶음 둘을 조립하게 되면 — 둘 중 먼저 오는 때에 — 나눈다. -- `@ConfigurationProperties` 클래스 하나는 capability namespace 하나를 가진다. -- 설정이 둘 이상 필요한 capability는 루트 클래스를 둔다. 루트가 `enabled` 조건, - `@EnableConfigurationProperties`, 관심사별 클래스의 `@Import`를 가진다. 아무것도 scan하지 않는다: - 조건이 걸린 루트에서 `@Import`해야 `enabled=false`가 권고가 아니라 실제로 끄는 스위치가 된다. - `cache-redis`의 `capability/RedisCapabilityConfig`가 참조 예다. 다시 쓸 Spring 조립을 가진 optional - 어댑터 capability는 자기 루트를 내놓는다. 알림은 `adapter:outbound:notification`의 - `NotificationPlatformAutoConfiguration`과 `composition:notification-platform`의 - `NotificationApplicationCompositionAutoConfiguration`을 쓴다. JPA는 - `adapter:outbound:persistence-jpa`의 package-private `PersistenceJpaAutoConfiguration`, - `PersistenceJpaRuntimeConfig`, `startup.JpaStartupAutoConfiguration`을 쓰고, 이 모듈은 기본 조립에 - 없다(`build.gradle`의 `// runtimeOnly project(':adapter:outbound:persistence-jpa')`). - Mongo도 같은 규칙을 따른다: persistence-mongo leaf가 MongoRootAutoConfiguration과 그 내부 health - bridge를 가지고, bootstrap은 Mongo 전용 운영 health 설정을 가지지 않는다. -- 나눈 capability의 공용 도우미는 `*Util` 바구니가 아니라 하는 일을 이름으로 단 자기 타입을 가진다 — - `cache-redis`의 `capability/RedisKeys`가 참조 예다. - -## 테스트 - -```bash -cd src -./gradlew :app-bootstrap:test -./gradlew verifyCleanArchitectureDependencies -``` +@AGENTS.md diff --git a/src/app-bootstrap/README.md b/src/app-bootstrap/README.md index 3881e831..4e196289 100644 --- a/src/app-bootstrap/README.md +++ b/src/app-bootstrap/README.md @@ -5,7 +5,7 @@ 이 모듈은 비즈니스 로직을 담지 않는다. Spring Boot 기동, 런타임 설정 바인딩, 기본 runtime 모듈 간 최종 와이어링, 그리고 composition classpath를 대상으로 한 중앙 아키텍처 테스트만 둔다. 모든 leaf의 프로젝트 edge는 JSON registry를 읽는 Gradle 방향 게이트가 별도로 검사한다. 허용/금지 의존, 책임 범위, 테스트 명령 같은 **모듈 규칙**의 -SSOT 는 [CLAUDE.md](CLAUDE.md) 다. +SSOT 는 [AGENTS.md](AGENTS.md) 다. 기본 composition의 SSOT는 `build.gradle`의 실제 project dependency graph다. registry는 runtime membership 목록을 두지 않는다. `allowed_dependencies` 밖의 project는 방향 게이트가 막는다. @@ -417,7 +417,7 @@ relay 조립(`OutboxRelayAutoConfiguration`, 스케줄러·metrics·leader token ## build.gradle — 의존성 구성 근거 app-bootstrap 은 합성 루트라 "왜 이 의존성이, 왜 이 scope 로" 결정이 많다. 빌드 파일에는 한 줄 -요약만 두고, 비자명한 근거는 여기에 모은다. 바탕 원칙은 **api vs implementation 정책**(CLAUDE.md): +요약만 두고, 비자명한 근거는 여기에 모은다. 바탕 원칙은 **api vs implementation 정책**(AGENTS.md): 모듈 간 의존은 기본 `implementation`이라 transitive 로 새지 않는다 — 그래서 테스트에서 그 타입이 필요하면 여기서 **명시적으로** 다시 선언한다. diff --git a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/FileserverUseCaseContractDeviationTest.java b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/FileserverUseCaseContractDeviationTest.java index a7ddeee5..9693d2ee 100644 --- a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/FileserverUseCaseContractDeviationTest.java +++ b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/FileserverUseCaseContractDeviationTest.java @@ -14,7 +14,7 @@ import org.junit.jupiter.api.Test; /** * Freezes what is left of the Fileserver's exemption from the inbound use-case contract. * - *

{@code application-core/CLAUDE.md} requires every inbound port implementation to extend {@code + *

{@code application-core/AGENTS.md} requires every inbound port implementation to extend {@code * CommandUseCase} or {@code QueryUseCase} and to declare {@code @UseCaseCapability}. The ArchUnit * rules that enforce it only match types that implement {@link UseCase}; a service that never does * is invisible to them. diff --git a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/ForbiddenApiArchitectureTest.java b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/ForbiddenApiArchitectureTest.java index 8d69bc6c..f3074b82 100644 --- a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/ForbiddenApiArchitectureTest.java +++ b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/ForbiddenApiArchitectureTest.java @@ -121,7 +121,7 @@ class ForbiddenApiArchitectureTest { + root + " lives in one of the listed operational contract packages, and the root holds" + " only its package-info; a business or domain concept belongs to the module that" - + " owns it (shared-contract CLAUDE.md)") + + " owns it (shared-contract AGENTS.md)") .allowEmptyShould(true); } diff --git a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/NamingConventionTest.java b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/NamingConventionTest.java index a0d58794..e271b74a 100644 --- a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/NamingConventionTest.java +++ b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/NamingConventionTest.java @@ -10,7 +10,7 @@ import org.springframework.boot.context.properties.ConfigurationProperties; /** * Naming convention enforcement — the machine-checkable subset of the naming table in {@code - * src/application-core/CLAUDE.md} ("Naming convention"), which is the rule book. + * src/application-core/AGENTS.md} ("Naming convention"), which is the rule book. * *

This test enforces only the rules that ArchUnit can decide reliably (N6 configuration binding, * I5 throwables, and the two package-ownership rules beside that table). The rest of that table — @@ -55,7 +55,7 @@ class NamingConventionTest { // Package ownership — a business feature package does not take a template package's name. The // template's own packages are listed in TemplatePackageOwnership (machine copy of the "Package - // ownership" table in src/application-core/CLAUDE.md); everything else under the two roots is a + // ownership" table in src/application-core/AGENTS.md); everything else under the two roots is a // feature, so a derived service adds features without editing the list. A feature always has a // domain package (docs/manual/03-placement.md ①), which is where a feature named after an // application template package — `operation`, `lock`, `cache` — shows up. diff --git a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnershipRuleTest.java b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnershipRuleTest.java index 0aaec0d7..9a2d7991 100644 --- a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnershipRuleTest.java +++ b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnershipRuleTest.java @@ -110,7 +110,7 @@ class TemplatePackageOwnershipRuleTest { .as( "a name in TemplatePackageOwnership.APPLICATION_PACKAGES that no longer exists was" + " renamed or removed without the list (and the table in" - + " src/application-core/CLAUDE.md) following it") + + " src/application-core/AGENTS.md) following it") .containsAll(TemplatePackageOwnership.APPLICATION_PACKAGES.keySet()); assertThat(domain) .as("TemplatePackageOwnership.DOMAIN_PACKAGES names a package that no longer exists") diff --git a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnership.java b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnership.java index 4e64b0ba..460dfacb 100644 --- a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnership.java +++ b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnership.java @@ -15,7 +15,7 @@ import java.util.TreeSet; * owns each, and which packages are a service's business features. * *

This is the machine copy of the "Package ownership" tables in {@code - * src/application-core/CLAUDE.md}, which are the rule book. A template change that adds, renames, + * src/application-core/AGENTS.md}, which are the rule book. A template change that adds, renames, * moves or removes one of these packages changes the table and this class together. Two tests hold * them to it: {@code TemplatePackageOwnershipDocumentTest} (document-contract lane, main stage) * fails when the table and this class differ in a name or an owning leaf, or when a listed package @@ -107,7 +107,7 @@ record TemplatePackageOwnership(String applicationRoot, String domainRoot) { + name.get() + "', a name the template already uses. A feature beside a template package" + " of the same name merges into the same tree on every upstream update." - + " Rename the feature (template packages: src/application-core/CLAUDE.md" + + " Rename the feature (template packages: src/application-core/AGENTS.md" + " \"Package ownership\").")); } } diff --git a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnershipDocumentTest.java b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnershipDocumentTest.java index 137c5a94..45d436d7 100644 --- a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnershipDocumentTest.java +++ b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnershipDocumentTest.java @@ -19,7 +19,7 @@ import org.junit.jupiter.api.Test; /** * The template package list exists twice — the "Package ownership" tables in {@code - * src/application-core/CLAUDE.md}, which people and agents read, and {@link + * src/application-core/AGENTS.md}, which people and agents read, and {@link * TemplatePackageOwnership}, which the architecture rules read — and nothing held the two together * (original review 2026-11-01 §16.3). Changing either one alone fails here: a name or an owning * leaf that differs, or a listed package that is not in the leaf the table says owns it. @@ -29,7 +29,7 @@ import org.junit.jupiter.api.Test; @Tag("document-contract") class TemplatePackageOwnershipDocumentTest { - private static final String RULE_BOOK = "src/application-core/CLAUDE.md"; + private static final String RULE_BOOK = "src/application-core/AGENTS.md"; private static final String REGISTRY = "src/config/architecture/modules.json"; private static final String APPLICATION_TABLE = "| 패키지 (`dev.caskeleton.application.*`) |"; private static final String DOMAIN_TABLE = "| 패키지 (`dev.caskeleton.domain.*`) |"; diff --git a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/messaging/MessagingPublicSurfaceContractTest.java b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/messaging/MessagingPublicSurfaceContractTest.java index 22527fd2..c42097b8 100644 --- a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/messaging/MessagingPublicSurfaceContractTest.java +++ b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/messaging/MessagingPublicSurfaceContractTest.java @@ -34,7 +34,7 @@ import org.junit.jupiter.api.Test; * *

So the rule is one-directional and mechanical: a vendor library named in a public or protected * signature is declared {@code api}; one used only behind private members stays {@code - * implementation}. {@code src/platforms/messaging/CLAUDE.md} states it as policy — this holds it to + * implementation}. {@code src/platforms/messaging/AGENTS.md} states it as policy — this holds it to * the source so the two cannot drift. * *

The libraries checked are the ones an adopter would otherwise have to reverse-engineer into diff --git a/src/app-bootstrap/src/test/java/dev/caskeleton/onboarding/domain/feature/FeatureAggregateRepository.java b/src/app-bootstrap/src/test/java/dev/caskeleton/onboarding/domain/feature/FeatureAggregateRepository.java index 24b168b7..ab409a98 100644 --- a/src/app-bootstrap/src/test/java/dev/caskeleton/onboarding/domain/feature/FeatureAggregateRepository.java +++ b/src/app-bootstrap/src/test/java/dev/caskeleton/onboarding/domain/feature/FeatureAggregateRepository.java @@ -3,7 +3,7 @@ package dev.caskeleton.onboarding.domain.feature; /** * Aggregate-level persistence for {@link FeatureAggregate}. The domain owns it because it stores * and returns whole aggregates — the {@code *Repository} side of the naming rule in {@code - * application-core/CLAUDE.md}; a technical store the application owns is a {@code *StorePort}. + * application-core/AGENTS.md}; a technical store the application owns is a {@code *StorePort}. */ public interface FeatureAggregateRepository { diff --git a/src/application-core/AGENTS.md b/src/application-core/AGENTS.md new file mode 100644 index 00000000..0a8a6bf0 --- /dev/null +++ b/src/application-core/AGENTS.md @@ -0,0 +1,336 @@ +# application-core — 애플리케이션 유스케이스 + +## 등록 정보 + +- 모듈 ID: `application-core` +- Gradle 경로: `:application-core` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :application-core:test --console=plain` +- 실행 기준: Java 21. 프레임워크 기준은 공용 버전 카탈로그(`src/gradle/libs.versions.toml`)가 고정한 Spring Boot 4.x다. +- registry 정본: `src/config/architecture/modules.json`. + +패키지 루트: `dev.caskeleton.application`. + +코드 주석에서 덜어낸 **설계 결정의 근거**는 [README.md](README.md) 가 모아둔다 (이 문서는 모듈 규칙 SSOT). + +## 책임 (Responsibility) + +- 유스케이스 inbound 포트(`CommandUseCase`, `QueryUseCase`)와 그 command·query 계약. +- 유스케이스가 의존하는 outbound 포트(`*Port` 인터페이스). +- 애플리케이션 예외와 정책 타입. +- 포트를 거쳐 도메인 모델을 조율한다. +- `TransactionPort` 추상화로 애플리케이션 트랜잭션 경계를 가진다. +- `CorrelationIdPort` 같은 포트로 프레임워크 없는 호출 문맥을 내놓는다. MDC 같은 실제 저장소는 + 어댑터가 가진다. +- 프레임워크 없는 integration event 초안(semantic draft), 검증된 이벤트의 값 계약, 정확한 타입의 + payload를 내놓는 SPI를 가진다. 메시징 semantic contract R1 경계까지만이다. + +## 허용 + +- `:domain-core` +- `:shared-contract` +- Java 표준 라이브러리 타입. + +## 금지 (Forbidden) + +- `adapter-*` 구현 클래스. +- `app-bootstrap`. +- controller의 요청·응답 DTO. +- JPA 엔티티와 Spring Data repository. +- HTTP 상태, 전송 타입(`org.springframework.web..`). +- `org.springframework.transaction.annotation.Transactional`(대신 `TransactionPort`를 쓴다). +- `org.springframework.context.ApplicationContext` — 직접 의존 금지 + (`getBean(Class)` 같은 리플렉션식 우회는 ArchUnit 규칙 `APPLICATION_DOES_NOT_DEPEND_ON_APPLICATION_CONTEXT`가 막는다). 문자열 키로 + bean을 찾기, `Class.forName(String)`, `BeanFactory#getBeansOfType`은 ArchUnit 정적 분석이 + 보지 못하는 곳이다. 코드 리뷰 체크리스트로 막는다. +- Lombok(`lombok..`) — `domain-core`에서도 금지다. `application-core`에서는 지금 Lombok이 + 계약 범위에 없다. 쓰려면 바이트코드가 불투명해지는 비용을 먼저 따진다. +- 이 모듈 안의 영속 계층 트랜잭션 애너테이션은 종류를 가리지 않고 금지다. +- 진단 프레임워크(`org.slf4j`, `java.util.logging`, Logback, Log4j, Micrometer). 진단 의도는 + 전용 outbound `*Port`로 나타내고, 어떻게 남길지는 어댑터가 정한다. +- 메시징 provider·런타임 타입: 물리 topic, Kafka record나 metadata, JSON tree·raw JSON payload, + serializer·schema validator 구현, 보안 토폴로지, publication epoch. + +## 계약 타입 + +| 타입 | 용도 | +|---|---| +| `usecase.UseCase` | inbound 포트의 기반 타입. 구체 inbound 포트는 반드시 `CommandUseCase`나 `QueryUseCase`를 상속한다. | +| `usecase.CommandUseCase` | 쓰기 유스케이스의 inbound 포트. 구현은 반드시 `@UseCaseCapability`를 단다. | +| `usecase.QueryUseCase` | 읽기 전용 유스케이스의 inbound 포트. 구현은 반드시 `transactionMode = READ_ONLY`와 `repositoryAccess = READ_REPOSITORY`를 선언한다. | +| `command.Command` | 쓰기 의도의 표지. 도메인 값으로 만든 평범한 불변 타입이다. | +| `query.Query` | 읽기 의도의 표지. 도메인 값으로 만든 평범한 불변 타입이다. | +| `transaction.TransactionPort` | 합류할 수 있는 쓰기·읽기, 물리 루트에서만 하는 쓰기, 독립 쓰기 경계를 내놓는 outbound 포트. `adapter:outbound:persistence-jpa`의 `SpringTransaction`이 구현한다. | +| `secret.SecretSourcePort` | 프레임워크 없는 outbound 비밀 해석 이음매. 배포가 app-bootstrap에서 backend를 고른다. 실제 환경 변수·클라우드·vault 리더는 outbound 어댑터 leaf에 둔다. | +| `transaction.NestedRootTransactionRejectedException` | `inRootWrite`가 실제로 열린 바깥 트랜잭션을 찾았을 때, action이나 provider 부작용 전에 바로 던지는 실패 신호. | +| `transaction.TransactionMode` | `WRITE` / `READ_ONLY` / `REQUIRES_NEW`. `NESTED`와 `NEVER`는 일부러 없다. | +| `transaction.Isolation` | `READ_COMMITTED`(고정 기본값) / `REPEATABLE_READ` / `SERIALIZABLE`. `READ_UNCOMMITTED`는 금지다(선언하지 않았다). vendor 기본값은 쓰지 않는다(엔진마다 기본값이 다르다 — PostgreSQL은 READ COMMITTED, MySQL InnoDB는 REPEATABLE READ). 더 엄격한 수준을 `TransactionPort`로 넘기는 일은 `feature-application-port-usecase-contract`와 함께 바꿀 `planned` 항목이다. 지금 호출 경로는 `READ_COMMITTED`로 고정한다. | +| `capability.UseCaseCapability` | 모든 구체 유스케이스에 반드시 다는 애너테이션: `transactionMode`, `idempotency`, `repositoryAccess`, `externalOutboundAllowed`를 선언한다. | +| `capability.Idempotency` | `IDEMPOTENT` / `KEYED` / `NOT_IDEMPOTENT`. | +| `capability.RepositoryAccess` | `NONE` / `READ_REPOSITORY` / `WRITE_REPOSITORY`. | +| `messaging.contract.IntegrationEventContractContribution

` | 닫힌 정확한 record payload 타입, 정해진 component 순서, 로컬 schema identity·hash, provider 중립 descriptor 기여. | +| `messaging.event.IntegrationEventDraft

` | 로컬 인코딩 전의 타입 있는 semantic 이벤트. JSON·Kafka·영속 상태가 아니다. `IntegrationEventDrafts`로만 만든다(`INTEGRATION_EVENT_DRAFTS_ARE_BUILT_BY_THE_SHARED_HELPER`). | +| `messaging.event.IntegrationEventDrafts` | 기능이 초안을 만드는 유일한 길: contract id·version·destination은 contract에서, correlation은 요청 값이 정규형이면 그 값(아니면 event id), 테넌트가 없는 기능은 `SINGLE_TENANT_SCOPE`. | +| `messaging.event.IntegrationIdentity` | event id, correlation·causation id, aggregate id의 유일한 문법과 길이 한계. 값은 `isCanonical(value, bound)`로 시험한다. 패턴을 복사하지 않는다. | +| `messaging.event.ValidatedIntegrationEvent` | 안정된 semantic identity와 바뀌지 않는 정확한 인코딩 바이트·hash. 뒤의 durable append 경계로 넘길 준비가 된 값이다. | +| `messaging.event.IntegrationEventEncoderPort` | 프레임워크 없는 로컬 경계(초안 → 검증된 이벤트). outbound 어댑터가 구현한다(템플릿은 `adapter:outbound:support`의 `JsonIntegrationEventEncoder`). | +| `outbox.OutboxAppendPort` | 유일한 outbox append: `ValidatedIntegrationEvent` 하나를 호출자의 쓰기 트랜잭션 안에서 넣는다. | +| `tenant.TenantId` | 테넌트 식별자와 그 유일한 문법(`[A-Za-z0-9][A-Za-z0-9_.-]{0,63}`). web과 GraphQL 전송 문맥이 모두 이 값을 싣는다. 전송 계층이 검증된 인증 데이터로만 만든다. | + +## 알림 (NOTIF-ADR-005) + +알림 타입은 이 leaf에 하나도 없다. `..notification.platform..`과 +`dev.caskeleton.application.notification` 바로 아래의 단순한 `NotificationPort`, `Notification`, +`NotificationChannel`은 모두 leaf `application-notification`의 것이다. 패키지 접두어가 같은 것이 +유일한 연결이다. R1 조율 타입은 2026-09-25에 지웠다. + +## 이름 규칙 (Naming convention) + +이 절이 저장소의 이름 규칙 정본이다. 기계로 볼 수 있는 행은 `NamingConventionTest`(app-bootstrap +architectureTest)가 강제한다. 나머지는 리뷰 규칙이고, 리뷰가 이 표와 대조한다. 새 기능은 「새 코드」 +열을 따른다. 「이미 있는 예외」는 누가 실수로 따라 하지 않게 이름을 적어 둔 것이다. + +| 역할 | 이름 | 위치 | 이미 있는 예외(따라 하지 않는다) | +|---|---|---|---| +| 유스케이스(inbound 포트 구현) | `UseCase`, ArchUnit이 강제 | 기능의 `application` 패키지 | `*ApplicationUseCase`(application-fileserver, application-notification), `*Service`(notification, fileserver) | +| command·query record | `*Command` / `*Query` | 그 유스케이스 옆 | — | +| aggregate 영속(aggregate 전체를 저장하고 돌려준다) | `Repository` | aggregate의 **domain** 패키지, 도메인이 가진다 | — | +| 애플리케이션이 가진 기술 저장소(outbox, 멱등성, operation 행) | `StorePort` | application 패키지 | `*WritePort`(옛 onboarding fixture, 지움) | +| aggregate가 아니라 projection을 돌려주는 읽기 모델 | `QueryPort` | application 패키지. projection만 돌려준다(ArchUnit) | — | +| 그 밖의 outbound 포트 | `Port` | application 패키지 | — | +| 서버가 정하는 id 생성 | `IdFactory extends IdFactory<Id>` | domain 패키지. id record는 `implements ResourceId` | `OutboxEventIdFactory`(샘플. event id는 resource id가 아니다) | +| 설정 바인딩 | `*Settings`(운영) 또는 `*Policy`(인가·도메인 정책), ArchUnit이 강제 | 그것을 바인딩하는 leaf | — | +| Throwable | `*Exception`, ArchUnit이 강제 | — | — | +| 포트의 계약 시험 키트 | 포트 소유자의 testFixtures에 둔 추상 `Contract`. fake의 시험과 각 어댑터의 시험이 상속한다 | testFixtures | 값 타입 시험의 이름이 한때 `*ContractTest`였다. 지금은 `*ValueTypesTest`다 | + +저장소의 한 줄 규칙: **도메인이 알아볼 만한 것을 저장하면 도메인의 `Repository`다. 애플리케이션에 +필요한 배관이면 application의 `StorePort`다.** + +## 패키지 소유 (Package ownership) + +이 절은 **템플릿이 어떤 패키지를 가지는지**와 업무 기능이 어디로 가는지의 정본이다. +`docs/manual/03-placement.md`가 이곳을 가리킨다. + +- 업무 기능은 `dev.caskeleton.application.`다(그리고 `dev.caskeleton.domain.`, + `...adapter.inbound.web.`, `...bootstrap.autoconfigure.`). 루트마다 바로 아래에 + 기능 하나당 패키지 하나를 두고, `command`·`usecase`·`port` 하위 패키지를 두지 않는다. +- ``는 아래 템플릿 패키지 이름 중 하나가 **아니다**. 같은 이름의 템플릿 패키지 옆에 둔 + 기능은 같은 패키지 트리에 들어가고, upstream 템플릿 갱신이 올 때마다 그 기능에 섞여 들어간다. +- 템플릿 패키지는 기능 패키지를 import하지 않는다. 이름이 맞아도 업무 코드를 템플릿 패키지에 넣지 + 않는다. +- 두 루트 아래에서 여기 적히지 않은 것은 모두 기능이다. 파생 서비스는 이 목록을 고치지 않고 기능을 + 더한다. 템플릿은 자기 패키지를 더하거나, 이름을 바꾸거나, 지울 때 이 목록을 고친다. + +| 패키지 (`dev.caskeleton.application.*`) | 소유 leaf | 담는 것 | +|---|---|---| +| `usecase`, `command`, `query` | application-core | inbound 포트 기반 타입과 command·query 표지 | +| `capability` | application-core | `@UseCaseCapability`와 그 enum | +| `transaction` | application-core | `TransactionPort`와 그 모드 | +| `security` | application-core | 인가 포트, `@RequiresPermission`, `@SystemInvoked`, `@SystemCaller`, `ObjectAccessPolicy` | +| `tenant` | application-core | `TenantId` | +| `observability` | application-core | `CorrelationIdPort`, `UserPrincipalPseudonymizerPort` | +| `secret` | application-core | `SecretSourcePort`, `SecretReference` | +| `messaging` | application-core | integration event semantic contract | +| `outbox` | application-core | 트랜잭션 outbox append와 relay | +| `idempotency` | application-core | 키 기반 멱등성 executor와 store 포트 | +| `operation` | application-core | durable(오래 걸리는) operation | +| `lease`, `lock` | application-core | 분산 lease·lock 포트 | +| `cache` | application-core | cache region 포트 | +| `realtime` | application-core | live event 재생 포트 | +| `notification` | application-notification | 알림 capability | +| `fileserver` | application-fileserver | 파일 서버 capability | +| `objectstorage` | application-objectstorage | 오브젝트 스토리지 capability(`content.CallBudget`은 그것이 싣는 호출 기한이다) | + +| 패키지 (`dev.caskeleton.domain.*`) | 소유 leaf | 담는 것 | +|---|---|---| +| `identifier` | domain-core | `ResourceId`, `IdFactory` | +| `stereotype` | domain-core | `@AggregateRoot`, `@DomainEvent`, `@ValueObject` | + +강제하는 곳: + +- `scripts/new-feature.sh`는 다섯 루트 중 어디든, 어느 leaf든 이미 패키지로 있는 기능 이름을 + 거절한다. 템플릿 패키지도 모두 여기 걸린다. +- `NamingConventionTest.FEATURE_PACKAGES_DO_NOT_REUSE_TEMPLATE_PACKAGE_NAMES`: 두 루트 아래의 기능 + 패키지는 이 표의 이름을 쓰지 않는다. 기능마다 domain 패키지가 있으므로 `operation`이라는 기능은 + `dev.caskeleton.domain.operation`에서 걸린다. +- `NamingConventionTest.TEMPLATE_PACKAGES_DO_NOT_DEPEND_ON_FEATURE_PACKAGES`: 템플릿 패키지 안에 쓴 + 기능 클래스는 템플릿 이름을 지니지만 자기 도메인을 import한다. 실패하는 것은 그 import다. +- 이 표가 정본이다. 규칙이 읽는 기계용 사본은 `TemplatePackageOwnership`이다(app-bootstrap + `src/test`에 있어서 architecture suite와 document-contract lane이 모두 본다). + `TemplatePackageOwnershipDocumentTest`(document-contract lane, `mainCheck`)는 표와 그 클래스의 + 패키지 이름이나 소유 leaf가 다르거나, 표에 적힌 패키지가 표가 말한 leaf에 없으면 실패한다. + `TemplatePackageOwnershipRuleTest`(architectureTest)는 적힌 이름이 운영 클래스 어디에도 없으면 + 실패한다. 새 템플릿 패키지는 같은 변경에서 둘 모두에 들어간다. +- 못 잡는 것: 아무도 적지 않은 새 템플릿 패키지. 기능은 같은 leaf에 생성되므로 + (`scripts/new-feature.sh`) 적히지 않은 패키지는 기능과 구별되지 않는다. 적는 것까지가 패키지를 + 더하는 일이다. +- 버린 대안: 적힌 최상위 패키지만 허용하기(파생 기능마다 템플릿 목록을 고쳐야 한다 — 기능마다 + 병합 충돌이 난다), 플랫폼 패키지용 `application-platform` leaf를 따로 두기(2026-11-01 성숙도 + 리뷰에서 따졌다: 경계는 더 분명하지만, 이름 규칙에 필요한 것보다 registry edge가 많아진다). + +## 정해진 유스케이스 모양 (Canonical use case shape) + +```java +@RequiresPermission("user:register") +@UseCaseCapability( + transactionMode = TransactionMode.WRITE, + idempotency = Idempotency.KEYED, + repositoryAccess = RepositoryAccess.WRITE_REPOSITORY) +public class RegisterUserUseCase implements CommandUseCase { + + private final UserRepository users; + private final TransactionPort tx; + + public RegisterUserUseCase(UserRepository users, TransactionPort tx) { + this.users = users; + this.tx = tx; + } + + @Override + public User handle(RegisterUserCommand cmd) { + return tx.inWrite(() -> { + // ... domain coordination + }); + } +} +``` + +이 클래스는 평범한 Java다. 조립 루트가 포트와 설정 값을 넣어 만든다. application-core는 DI +프레임워크에 스스로 등록하지 않는다. 클래스는 **final이 아니다**: 상태를 바꾸는 유스케이스는 +`@RequiresPermission`을 선언하고, web 어댑터는 CGLIB proxy로 그것을 강제하는데, CGLIB는 final +클래스를 상속하지 못한다(`RequiresPermissionProxyabilityTest`). 같은 이유로 bean으로 등록한다. +`new`로 만든 유스케이스는 검사를 받지 않는다. 시스템만 부르는 유스케이스(스케줄러, relay, 메시지 +소비자)는 권한 대신 `@SystemInvoked(reason = ...)`를 달고 bean이 아니다. 권한 검사가 없는 쓰기라서 +사용자 요청이 닿으면 안 되기 때문이다. 그 시스템 호출자가 유스케이스를 만든다: 스케줄러는 조립 +모듈, 메시지 핸들러는 `..adapter.inbound.messaging..` 안의 `@SystemCaller(reason = ...)`, 예약 +작업은 서비스 자신의 `..adapter.inbound.scheduler..` 패키지 안의 `@SystemCaller`다. 이 셋과 각각의 +위치는 `docs/manual/07-authorization.md` 「시스템이 부르는 쓰기」가 정본 목록이다. 모두 강제된다: +`@SystemInvoked` bean은 기동에 실패한다. `@SystemCaller`가 아닌 inbound 어댑터가 그 유스케이스에 +의존하면 `ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`가 실패한다. +`SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS`는 그 표지(그리고 표지가 붙은 클래스 안에 든 +클래스)를 사용자 전송 계층에 두지 못하게 한다. `USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`는 사용자 +전송 계층이 시스템 호출자를 부르지 못하게 한다(그 클래스로든, 그것이 구현한 프로젝트 인터페이스로든). +`SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES`는 시스템 호출자가 `Runnable`이나 프로젝트 밖의 다른 +타입이 되지 못하게 한다. 그런 타입은 어떤 의존 규칙도 따라가지 못한다. 타입 이름이 드러나지 않는 +경로(이름으로 찾는 bean, 설정이 넘겨주는 함수)는 보지 못한다. 매뉴얼 07장이 그 경로와 그것을 막는 +곳을 적는다. `@RequiresPermission` bean이 있는데 강제할 advisor가 없는 조립도 기동에 실패한다 +(`composition:service-runtime`의 `PermissionEnforcementGuard`, 두 검사 모두). + +## 허용하는 트랜잭션 모양 (Allowed transactional shapes) + +| 유스케이스 모양 | `transactionMode` | TransactionPort 호출 | 언제 | +|---|---|---|---| +| 쓰기 command | `WRITE` | `tx.inWrite(...)` | `CommandUseCase`의 기본. | +| 물리 루트 쓰기 command | `WRITE` | `tx.inRootWrite(...)` | 바깥 트랜잭션이 없음을 증명하고 커밋 뒤에 결과를 내놓아야 하는 조율일 때만. | +| 읽기 전용 query | `READ_ONLY` | `tx.inRead(...)` | `QueryUseCase`의 기본. | +| outbox·감사·보상 | `REQUIRES_NEW` | `tx.inNew(...)` | 유스케이스가 반드시 호출자와 따로 커밋해야 할 때만. | + +`NESTED`와 `NEVER` 전파는 금지다. +`inRootWrite`는 action이나 `PlatformTransactionManager`를 부르기 전에 실제로 열린 바깥 트랜잭션을 +반드시 거절한다. 루트 전용 동작을 `REQUIRES_NEW`로 흉내 내면 안 된다. +`WRITE_REPOSITORY + WRITE` 유스케이스의 직접 경계 적합성 규칙은 `inWrite`와 `inRootWrite`가 모두 +만족한다. READ와 REQUIRES_NEW의 대응은 계속 서로 배타적이다. + +### 콜백 시그니처 계약 + +`TransactionPort` 콜백은 `Supplier` / `Runnable`이라 checked 예외를 던지지 못한다. Spring +`TransactionCallback`의 제약과 같다. 도메인의 checked 예외는 `RuntimeException` 하위 클래스로 +감싼다(`DomainException extends RuntimeException`). `IOException`은 `UncheckedIOException`으로 +감싼다. `SQLException`은 Spring의 `DataAccessException` 계층이 자동으로 번역한다. + +### `inNew` 풀 크기 제약 + +`inNew`는 새 물리 JDBC 연결을 얻는다. 풀 크기는 반드시 다음을 만족한다. + +``` +hikari.maximumPoolSize >= (concurrent_threads × (1 + max_inNew_depth)) + 1 +``` + +**금지**: 많은 레코드를 도는 반복문 안에서 `tx.inNew(...)`를 부른다 — 풀이 바닥나고 교착이 생길 +수 있다. 레코드를 `inNew` 호출 **하나** 안에서 묶어 처리하거나, 반복문을 트랜잭션 경계 밖으로 뺀다. + +## 멱등성 (KEYED) — feature-rate-limit-idempotency-contract + +`@UseCaseCapability(idempotency = Idempotency.KEYED)`는 **지원한다**. KEYED 유스케이스는 자기 일을 +`dev.caskeleton.application.idempotency.IdempotencyExecutor`로 감싼다. 소유자를 안전하게 지키는 +유일한 세대다. V1 `IdempotencyScope`/`tryBegin` API는 없어졌다. + +- **범위(scope)**: 호출자가 `IdempotencyScopeDigest`를 넘긴다. principal + client key + operation + code의 버전 있는 HMAC이고, executor가 받기 전에 계산한다. 원본 `Idempotency-Key`는 이 계층에도 + store에도 닿지 않는다. +- **store**: `IdempotencyStorePort`. `app.capabilities.idempotency.provider`로 고른 provider 정확히 + 하나가 내놓는다(`redis` → `cache-redis`, `postgresql` → `persistence-jpa`, 기본값 `disabled`). + 운영에서 메모리 저장소는 금지다. +- **executor**: `composition:idempotency`의 `IdempotencyAutoConfiguration`이 `IdempotencySettings`로 + 한 번 만든다(처리 lease 30s, 재생 TTL `APP_IDEMPOTENCY_TTL` 24h ≤72h이고 lease보다 짧지 않다, 실패 + 보존 24h이고 재생 TTL보다 짧지 않다). 유스케이스나 서비스 자신의 설정에서 만들지 않는다. +- action은 `IdempotentAction.Outcome`(`Success` / `RetryableNoEffect` / `EffectUnknown`)을 + 돌려준다. 던진 예외는 효과를 모름(effect-unknown)으로 센다. 처리 중이면 409 + `IDEMPOTENT_IN_FLIGHT`, fingerprint(SHA-256)가 다르면 422 `IDEMPOTENT_REQUEST_MISMATCH`다. + `IdempotencyUnavailableException`과 `IdempotencyRecoveryRequiredException`은 store가 결과를 + 증명하지 못했다는 뜻이니 무턱대고 다시 시도하지 않는다. +- 모든 store는 처리 lease가 끝난 실행에 `RecoveryRequired`로 답하고 그 실행을 넘겨받지 않는다. + 넘겨받는 것은 시작하지 않은 claim이나 다시 시도할 수 있는 실패뿐이다. 이 답은 레코드를 가진 + 쪽에게 남긴다: 가진 쪽이 늦게 보낸 첫 `complete`/`markFailed`는 기록한다. lease가 끝난 것은 + 갱신하지 않고, lease가 끝난 claim은 시작하지 않는다. 둘 다 `NOT_OWNER`가 아니라 `LEASE_EXPIRED`로 + 답하고, executor는 거절된 시작을 「적용 안 됨」으로 바꾼다(소유자 결정 2026-11-04). 레코드는 + lease에 재생 TTL을 더한 만큼 산다. `IdempotencyStoreContract`가 Redis와 PostgreSQL을 실제 서버에서 + 둘 모두에 맞춘다. 메모리 fake는 시간을 모델링하지 않으니 계약 중 시간이 없는 경우만 돈다. +- 모든 전이는 그 레코드를 claim한 operation을 이름으로 댄다(`IdempotencyOwner.claimOperationId()`). + 다른 operation이면 모든 store에서 `OPERATION_CONFLICT`이고 아무것도 바꾸지 않는다. owner token을 + 다른 operation으로 가져온 조회도 같다(소유자 결정 2026-11-06). +- 이미 적용된 전이는 그것을 적용한 handle에게만 「already …」로 확인해 준다. 그 handle은 그 전이로 + 옮겨 간, 한 revision 뒤의 레코드다. 다른 handle은 모두 `NOT_OWNER`다. 넘겨받기 전의 같은 시도의 + handle도, 갱신을 적용한 handle로 하는 시작도 그렇다. 놓아준 handle로 하는 시작은 store가 놓아준 + 레코드를 남기느냐에 따라 `ABSENT`나 `NOT_OWNER`다(소유자 결정 2026-11-06, + `IdempotencyStoreContract`). +- 적용한 handle이 다른 disposition으로 `markFailed`를 다시 보내면 `OPERATION_CONFLICT`이고 기록된 + 실패가 남는다. retention만 다르면 `ALREADY_MARKED_SAME_OPERATION`이고 처음 retention이 남는다 — + retention은 완료의 재생 TTL처럼 비교하지 않는다(소유자 결정 2026-11-07). + +예전 ArchUnit 동결 규칙 `inbound_port_implementations_do_not_declare_keyed_idempotency`와 그 fixture는 +이 브랜치가 병합될 때 지웠다. + +## 읽기·query 경로 (feature-application-query-bypass-contract) + +읽기 쪽에는 똑같이 유효한 모양이 둘 있다. 읽기마다 고르고, 하나를 강요하지 않는다. + +| 모양 | 돌려주는 것 | 언제 | 어떻게 | +|---|---|---|---| +| **aggregate를 거쳐서**(단순 읽기의 기본) | `*Repository` 포트로 받은 도메인 aggregate | 읽기 모양 == 쓰기 aggregate **이고** aggregate가 최소 불변식 경계일 때(지연 컬렉션이 필요 없음) | `QueryUseCase` → repository 포트 → `Order` | +| **projection (CQRS-lite)** | `*QueryPort`로 받은 애플리케이션 계층 projection DTO | 읽기 모양 ≠ 쓰기, 또는 aggregate 수화·지연 컬렉션 join을 건너뛰려 할 때 | `QueryUseCase` → `*QueryPort` → `OrderSummary`(record). query는 JPQL `SELECT new` / JdbcTemplate | + +- **순수성 가드레일(core, 기계로 강제):** 단순 이름이 `QueryPort`로 끝나는 읽기 포트는 반드시 + 애플리케이션 계층 projection DTO만 돌려준다 — 도메인 aggregate, JPA 엔티티, web 타입은 **제네릭 + 타입 인자를 거쳐서도**(`List`) 안 된다. ArchUnit + `QUERY_PORTS_DO_NOT_LEAK_DOMAIN_JPA_OR_WEB_TYPES`가 강제한다. projection 사용 자체는 강요된 기본이 + 아니라 **선택**이다. +- **엄격한 절차:** 모든 읽기는 `QueryUseCase` bean을 거친다. web → 읽기 포트로 바로 가는 얇은 + 경로는 없다. 그런 경로는 필수인 `@UseCaseCapability` 적합성 검사를 건너뛴다. +- **트랜잭션:** 읽기의 기본은 `TransactionPort.inRead`다. 트랜잭션 없는(autocommit) 읽기는 + `spring.jpa.open-in-view=false`가 확인됐고 **그리고** 읽기가 projection만 쓰고(지연 접근 없음) + **그리고** 문장 하나일 때만 고를 수 있다. 아니면 `inRead`를 쓴다. +- **capability:** repository를 쓰는 projection 읽기도 `repositoryAccess = READ_REPOSITORY`다. + 「projection이냐 aggregate냐」는 돌려주는 *모양* 축이고, repository 접근 *수준* 축과 따로다 — 새 + enum이 없다. outbound HTTP 읽기(repository 없음)는 `RepositoryAccess.NONE`이다. +- 물리적으로 따로 둔 읽기 저장소를 쓰는 완전한 CQRS는 범위 밖이다. 올려서 정할 일이다. + +## ArchUnit 가드레일(강제됨) + +- `APPLICATION_DOES_NOT_DEPEND_ON_ADAPTERS_OR_TRANSPORT` +- `APPLICATION_DOES_NOT_USE_SPRING_TRANSACTIONAL_ANNOTATION` +- `APPLICATION_DOES_NOT_DEPEND_ON_APPLICATION_CONTEXT` +- `APPLICATION_HAS_NO_DIAGNOSTIC_FRAMEWORK` +- `INBOUND_PORT_IMPLEMENTATIONS_END_WITH_USE_CASE` +- `INBOUND_PORT_IMPLEMENTATIONS_DECLARE_CAPABILITY` +- `QUERY_PORTS_DO_NOT_LEAK_DOMAIN_JPA_OR_WEB_TYPES`(`*QueryPort` 반환 순수성) + +## 테스트 + +```bash +cd src +./gradlew :application-core:test +./gradlew :app-bootstrap:architectureTest +``` + +위 메시징 타입은 semantic contract R1까지만 세운다. JSON Schema 검증, Kafka 발행, durable outbox +영속, 그 밖의 메시징 R2 capability를 주장하지 않는다. diff --git a/src/application-core/CLAUDE.md b/src/application-core/CLAUDE.md index 0a8a6bf0..43c994c2 100644 --- a/src/application-core/CLAUDE.md +++ b/src/application-core/CLAUDE.md @@ -1,336 +1 @@ -# application-core — 애플리케이션 유스케이스 - -## 등록 정보 - -- 모듈 ID: `application-core` -- Gradle 경로: `:application-core` -- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :application-core:test --console=plain` -- 실행 기준: Java 21. 프레임워크 기준은 공용 버전 카탈로그(`src/gradle/libs.versions.toml`)가 고정한 Spring Boot 4.x다. -- registry 정본: `src/config/architecture/modules.json`. - -패키지 루트: `dev.caskeleton.application`. - -코드 주석에서 덜어낸 **설계 결정의 근거**는 [README.md](README.md) 가 모아둔다 (이 문서는 모듈 규칙 SSOT). - -## 책임 (Responsibility) - -- 유스케이스 inbound 포트(`CommandUseCase`, `QueryUseCase`)와 그 command·query 계약. -- 유스케이스가 의존하는 outbound 포트(`*Port` 인터페이스). -- 애플리케이션 예외와 정책 타입. -- 포트를 거쳐 도메인 모델을 조율한다. -- `TransactionPort` 추상화로 애플리케이션 트랜잭션 경계를 가진다. -- `CorrelationIdPort` 같은 포트로 프레임워크 없는 호출 문맥을 내놓는다. MDC 같은 실제 저장소는 - 어댑터가 가진다. -- 프레임워크 없는 integration event 초안(semantic draft), 검증된 이벤트의 값 계약, 정확한 타입의 - payload를 내놓는 SPI를 가진다. 메시징 semantic contract R1 경계까지만이다. - -## 허용 - -- `:domain-core` -- `:shared-contract` -- Java 표준 라이브러리 타입. - -## 금지 (Forbidden) - -- `adapter-*` 구현 클래스. -- `app-bootstrap`. -- controller의 요청·응답 DTO. -- JPA 엔티티와 Spring Data repository. -- HTTP 상태, 전송 타입(`org.springframework.web..`). -- `org.springframework.transaction.annotation.Transactional`(대신 `TransactionPort`를 쓴다). -- `org.springframework.context.ApplicationContext` — 직접 의존 금지 - (`getBean(Class)` 같은 리플렉션식 우회는 ArchUnit 규칙 `APPLICATION_DOES_NOT_DEPEND_ON_APPLICATION_CONTEXT`가 막는다). 문자열 키로 - bean을 찾기, `Class.forName(String)`, `BeanFactory#getBeansOfType`은 ArchUnit 정적 분석이 - 보지 못하는 곳이다. 코드 리뷰 체크리스트로 막는다. -- Lombok(`lombok..`) — `domain-core`에서도 금지다. `application-core`에서는 지금 Lombok이 - 계약 범위에 없다. 쓰려면 바이트코드가 불투명해지는 비용을 먼저 따진다. -- 이 모듈 안의 영속 계층 트랜잭션 애너테이션은 종류를 가리지 않고 금지다. -- 진단 프레임워크(`org.slf4j`, `java.util.logging`, Logback, Log4j, Micrometer). 진단 의도는 - 전용 outbound `*Port`로 나타내고, 어떻게 남길지는 어댑터가 정한다. -- 메시징 provider·런타임 타입: 물리 topic, Kafka record나 metadata, JSON tree·raw JSON payload, - serializer·schema validator 구현, 보안 토폴로지, publication epoch. - -## 계약 타입 - -| 타입 | 용도 | -|---|---| -| `usecase.UseCase` | inbound 포트의 기반 타입. 구체 inbound 포트는 반드시 `CommandUseCase`나 `QueryUseCase`를 상속한다. | -| `usecase.CommandUseCase` | 쓰기 유스케이스의 inbound 포트. 구현은 반드시 `@UseCaseCapability`를 단다. | -| `usecase.QueryUseCase` | 읽기 전용 유스케이스의 inbound 포트. 구현은 반드시 `transactionMode = READ_ONLY`와 `repositoryAccess = READ_REPOSITORY`를 선언한다. | -| `command.Command` | 쓰기 의도의 표지. 도메인 값으로 만든 평범한 불변 타입이다. | -| `query.Query` | 읽기 의도의 표지. 도메인 값으로 만든 평범한 불변 타입이다. | -| `transaction.TransactionPort` | 합류할 수 있는 쓰기·읽기, 물리 루트에서만 하는 쓰기, 독립 쓰기 경계를 내놓는 outbound 포트. `adapter:outbound:persistence-jpa`의 `SpringTransaction`이 구현한다. | -| `secret.SecretSourcePort` | 프레임워크 없는 outbound 비밀 해석 이음매. 배포가 app-bootstrap에서 backend를 고른다. 실제 환경 변수·클라우드·vault 리더는 outbound 어댑터 leaf에 둔다. | -| `transaction.NestedRootTransactionRejectedException` | `inRootWrite`가 실제로 열린 바깥 트랜잭션을 찾았을 때, action이나 provider 부작용 전에 바로 던지는 실패 신호. | -| `transaction.TransactionMode` | `WRITE` / `READ_ONLY` / `REQUIRES_NEW`. `NESTED`와 `NEVER`는 일부러 없다. | -| `transaction.Isolation` | `READ_COMMITTED`(고정 기본값) / `REPEATABLE_READ` / `SERIALIZABLE`. `READ_UNCOMMITTED`는 금지다(선언하지 않았다). vendor 기본값은 쓰지 않는다(엔진마다 기본값이 다르다 — PostgreSQL은 READ COMMITTED, MySQL InnoDB는 REPEATABLE READ). 더 엄격한 수준을 `TransactionPort`로 넘기는 일은 `feature-application-port-usecase-contract`와 함께 바꿀 `planned` 항목이다. 지금 호출 경로는 `READ_COMMITTED`로 고정한다. | -| `capability.UseCaseCapability` | 모든 구체 유스케이스에 반드시 다는 애너테이션: `transactionMode`, `idempotency`, `repositoryAccess`, `externalOutboundAllowed`를 선언한다. | -| `capability.Idempotency` | `IDEMPOTENT` / `KEYED` / `NOT_IDEMPOTENT`. | -| `capability.RepositoryAccess` | `NONE` / `READ_REPOSITORY` / `WRITE_REPOSITORY`. | -| `messaging.contract.IntegrationEventContractContribution

` | 닫힌 정확한 record payload 타입, 정해진 component 순서, 로컬 schema identity·hash, provider 중립 descriptor 기여. | -| `messaging.event.IntegrationEventDraft

` | 로컬 인코딩 전의 타입 있는 semantic 이벤트. JSON·Kafka·영속 상태가 아니다. `IntegrationEventDrafts`로만 만든다(`INTEGRATION_EVENT_DRAFTS_ARE_BUILT_BY_THE_SHARED_HELPER`). | -| `messaging.event.IntegrationEventDrafts` | 기능이 초안을 만드는 유일한 길: contract id·version·destination은 contract에서, correlation은 요청 값이 정규형이면 그 값(아니면 event id), 테넌트가 없는 기능은 `SINGLE_TENANT_SCOPE`. | -| `messaging.event.IntegrationIdentity` | event id, correlation·causation id, aggregate id의 유일한 문법과 길이 한계. 값은 `isCanonical(value, bound)`로 시험한다. 패턴을 복사하지 않는다. | -| `messaging.event.ValidatedIntegrationEvent` | 안정된 semantic identity와 바뀌지 않는 정확한 인코딩 바이트·hash. 뒤의 durable append 경계로 넘길 준비가 된 값이다. | -| `messaging.event.IntegrationEventEncoderPort` | 프레임워크 없는 로컬 경계(초안 → 검증된 이벤트). outbound 어댑터가 구현한다(템플릿은 `adapter:outbound:support`의 `JsonIntegrationEventEncoder`). | -| `outbox.OutboxAppendPort` | 유일한 outbox append: `ValidatedIntegrationEvent` 하나를 호출자의 쓰기 트랜잭션 안에서 넣는다. | -| `tenant.TenantId` | 테넌트 식별자와 그 유일한 문법(`[A-Za-z0-9][A-Za-z0-9_.-]{0,63}`). web과 GraphQL 전송 문맥이 모두 이 값을 싣는다. 전송 계층이 검증된 인증 데이터로만 만든다. | - -## 알림 (NOTIF-ADR-005) - -알림 타입은 이 leaf에 하나도 없다. `..notification.platform..`과 -`dev.caskeleton.application.notification` 바로 아래의 단순한 `NotificationPort`, `Notification`, -`NotificationChannel`은 모두 leaf `application-notification`의 것이다. 패키지 접두어가 같은 것이 -유일한 연결이다. R1 조율 타입은 2026-09-25에 지웠다. - -## 이름 규칙 (Naming convention) - -이 절이 저장소의 이름 규칙 정본이다. 기계로 볼 수 있는 행은 `NamingConventionTest`(app-bootstrap -architectureTest)가 강제한다. 나머지는 리뷰 규칙이고, 리뷰가 이 표와 대조한다. 새 기능은 「새 코드」 -열을 따른다. 「이미 있는 예외」는 누가 실수로 따라 하지 않게 이름을 적어 둔 것이다. - -| 역할 | 이름 | 위치 | 이미 있는 예외(따라 하지 않는다) | -|---|---|---|---| -| 유스케이스(inbound 포트 구현) | `UseCase`, ArchUnit이 강제 | 기능의 `application` 패키지 | `*ApplicationUseCase`(application-fileserver, application-notification), `*Service`(notification, fileserver) | -| command·query record | `*Command` / `*Query` | 그 유스케이스 옆 | — | -| aggregate 영속(aggregate 전체를 저장하고 돌려준다) | `Repository` | aggregate의 **domain** 패키지, 도메인이 가진다 | — | -| 애플리케이션이 가진 기술 저장소(outbox, 멱등성, operation 행) | `StorePort` | application 패키지 | `*WritePort`(옛 onboarding fixture, 지움) | -| aggregate가 아니라 projection을 돌려주는 읽기 모델 | `QueryPort` | application 패키지. projection만 돌려준다(ArchUnit) | — | -| 그 밖의 outbound 포트 | `Port` | application 패키지 | — | -| 서버가 정하는 id 생성 | `IdFactory extends IdFactory<Id>` | domain 패키지. id record는 `implements ResourceId` | `OutboxEventIdFactory`(샘플. event id는 resource id가 아니다) | -| 설정 바인딩 | `*Settings`(운영) 또는 `*Policy`(인가·도메인 정책), ArchUnit이 강제 | 그것을 바인딩하는 leaf | — | -| Throwable | `*Exception`, ArchUnit이 강제 | — | — | -| 포트의 계약 시험 키트 | 포트 소유자의 testFixtures에 둔 추상 `Contract`. fake의 시험과 각 어댑터의 시험이 상속한다 | testFixtures | 값 타입 시험의 이름이 한때 `*ContractTest`였다. 지금은 `*ValueTypesTest`다 | - -저장소의 한 줄 규칙: **도메인이 알아볼 만한 것을 저장하면 도메인의 `Repository`다. 애플리케이션에 -필요한 배관이면 application의 `StorePort`다.** - -## 패키지 소유 (Package ownership) - -이 절은 **템플릿이 어떤 패키지를 가지는지**와 업무 기능이 어디로 가는지의 정본이다. -`docs/manual/03-placement.md`가 이곳을 가리킨다. - -- 업무 기능은 `dev.caskeleton.application.`다(그리고 `dev.caskeleton.domain.`, - `...adapter.inbound.web.`, `...bootstrap.autoconfigure.`). 루트마다 바로 아래에 - 기능 하나당 패키지 하나를 두고, `command`·`usecase`·`port` 하위 패키지를 두지 않는다. -- ``는 아래 템플릿 패키지 이름 중 하나가 **아니다**. 같은 이름의 템플릿 패키지 옆에 둔 - 기능은 같은 패키지 트리에 들어가고, upstream 템플릿 갱신이 올 때마다 그 기능에 섞여 들어간다. -- 템플릿 패키지는 기능 패키지를 import하지 않는다. 이름이 맞아도 업무 코드를 템플릿 패키지에 넣지 - 않는다. -- 두 루트 아래에서 여기 적히지 않은 것은 모두 기능이다. 파생 서비스는 이 목록을 고치지 않고 기능을 - 더한다. 템플릿은 자기 패키지를 더하거나, 이름을 바꾸거나, 지울 때 이 목록을 고친다. - -| 패키지 (`dev.caskeleton.application.*`) | 소유 leaf | 담는 것 | -|---|---|---| -| `usecase`, `command`, `query` | application-core | inbound 포트 기반 타입과 command·query 표지 | -| `capability` | application-core | `@UseCaseCapability`와 그 enum | -| `transaction` | application-core | `TransactionPort`와 그 모드 | -| `security` | application-core | 인가 포트, `@RequiresPermission`, `@SystemInvoked`, `@SystemCaller`, `ObjectAccessPolicy` | -| `tenant` | application-core | `TenantId` | -| `observability` | application-core | `CorrelationIdPort`, `UserPrincipalPseudonymizerPort` | -| `secret` | application-core | `SecretSourcePort`, `SecretReference` | -| `messaging` | application-core | integration event semantic contract | -| `outbox` | application-core | 트랜잭션 outbox append와 relay | -| `idempotency` | application-core | 키 기반 멱등성 executor와 store 포트 | -| `operation` | application-core | durable(오래 걸리는) operation | -| `lease`, `lock` | application-core | 분산 lease·lock 포트 | -| `cache` | application-core | cache region 포트 | -| `realtime` | application-core | live event 재생 포트 | -| `notification` | application-notification | 알림 capability | -| `fileserver` | application-fileserver | 파일 서버 capability | -| `objectstorage` | application-objectstorage | 오브젝트 스토리지 capability(`content.CallBudget`은 그것이 싣는 호출 기한이다) | - -| 패키지 (`dev.caskeleton.domain.*`) | 소유 leaf | 담는 것 | -|---|---|---| -| `identifier` | domain-core | `ResourceId`, `IdFactory` | -| `stereotype` | domain-core | `@AggregateRoot`, `@DomainEvent`, `@ValueObject` | - -강제하는 곳: - -- `scripts/new-feature.sh`는 다섯 루트 중 어디든, 어느 leaf든 이미 패키지로 있는 기능 이름을 - 거절한다. 템플릿 패키지도 모두 여기 걸린다. -- `NamingConventionTest.FEATURE_PACKAGES_DO_NOT_REUSE_TEMPLATE_PACKAGE_NAMES`: 두 루트 아래의 기능 - 패키지는 이 표의 이름을 쓰지 않는다. 기능마다 domain 패키지가 있으므로 `operation`이라는 기능은 - `dev.caskeleton.domain.operation`에서 걸린다. -- `NamingConventionTest.TEMPLATE_PACKAGES_DO_NOT_DEPEND_ON_FEATURE_PACKAGES`: 템플릿 패키지 안에 쓴 - 기능 클래스는 템플릿 이름을 지니지만 자기 도메인을 import한다. 실패하는 것은 그 import다. -- 이 표가 정본이다. 규칙이 읽는 기계용 사본은 `TemplatePackageOwnership`이다(app-bootstrap - `src/test`에 있어서 architecture suite와 document-contract lane이 모두 본다). - `TemplatePackageOwnershipDocumentTest`(document-contract lane, `mainCheck`)는 표와 그 클래스의 - 패키지 이름이나 소유 leaf가 다르거나, 표에 적힌 패키지가 표가 말한 leaf에 없으면 실패한다. - `TemplatePackageOwnershipRuleTest`(architectureTest)는 적힌 이름이 운영 클래스 어디에도 없으면 - 실패한다. 새 템플릿 패키지는 같은 변경에서 둘 모두에 들어간다. -- 못 잡는 것: 아무도 적지 않은 새 템플릿 패키지. 기능은 같은 leaf에 생성되므로 - (`scripts/new-feature.sh`) 적히지 않은 패키지는 기능과 구별되지 않는다. 적는 것까지가 패키지를 - 더하는 일이다. -- 버린 대안: 적힌 최상위 패키지만 허용하기(파생 기능마다 템플릿 목록을 고쳐야 한다 — 기능마다 - 병합 충돌이 난다), 플랫폼 패키지용 `application-platform` leaf를 따로 두기(2026-11-01 성숙도 - 리뷰에서 따졌다: 경계는 더 분명하지만, 이름 규칙에 필요한 것보다 registry edge가 많아진다). - -## 정해진 유스케이스 모양 (Canonical use case shape) - -```java -@RequiresPermission("user:register") -@UseCaseCapability( - transactionMode = TransactionMode.WRITE, - idempotency = Idempotency.KEYED, - repositoryAccess = RepositoryAccess.WRITE_REPOSITORY) -public class RegisterUserUseCase implements CommandUseCase { - - private final UserRepository users; - private final TransactionPort tx; - - public RegisterUserUseCase(UserRepository users, TransactionPort tx) { - this.users = users; - this.tx = tx; - } - - @Override - public User handle(RegisterUserCommand cmd) { - return tx.inWrite(() -> { - // ... domain coordination - }); - } -} -``` - -이 클래스는 평범한 Java다. 조립 루트가 포트와 설정 값을 넣어 만든다. application-core는 DI -프레임워크에 스스로 등록하지 않는다. 클래스는 **final이 아니다**: 상태를 바꾸는 유스케이스는 -`@RequiresPermission`을 선언하고, web 어댑터는 CGLIB proxy로 그것을 강제하는데, CGLIB는 final -클래스를 상속하지 못한다(`RequiresPermissionProxyabilityTest`). 같은 이유로 bean으로 등록한다. -`new`로 만든 유스케이스는 검사를 받지 않는다. 시스템만 부르는 유스케이스(스케줄러, relay, 메시지 -소비자)는 권한 대신 `@SystemInvoked(reason = ...)`를 달고 bean이 아니다. 권한 검사가 없는 쓰기라서 -사용자 요청이 닿으면 안 되기 때문이다. 그 시스템 호출자가 유스케이스를 만든다: 스케줄러는 조립 -모듈, 메시지 핸들러는 `..adapter.inbound.messaging..` 안의 `@SystemCaller(reason = ...)`, 예약 -작업은 서비스 자신의 `..adapter.inbound.scheduler..` 패키지 안의 `@SystemCaller`다. 이 셋과 각각의 -위치는 `docs/manual/07-authorization.md` 「시스템이 부르는 쓰기」가 정본 목록이다. 모두 강제된다: -`@SystemInvoked` bean은 기동에 실패한다. `@SystemCaller`가 아닌 inbound 어댑터가 그 유스케이스에 -의존하면 `ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`가 실패한다. -`SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS`는 그 표지(그리고 표지가 붙은 클래스 안에 든 -클래스)를 사용자 전송 계층에 두지 못하게 한다. `USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`는 사용자 -전송 계층이 시스템 호출자를 부르지 못하게 한다(그 클래스로든, 그것이 구현한 프로젝트 인터페이스로든). -`SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES`는 시스템 호출자가 `Runnable`이나 프로젝트 밖의 다른 -타입이 되지 못하게 한다. 그런 타입은 어떤 의존 규칙도 따라가지 못한다. 타입 이름이 드러나지 않는 -경로(이름으로 찾는 bean, 설정이 넘겨주는 함수)는 보지 못한다. 매뉴얼 07장이 그 경로와 그것을 막는 -곳을 적는다. `@RequiresPermission` bean이 있는데 강제할 advisor가 없는 조립도 기동에 실패한다 -(`composition:service-runtime`의 `PermissionEnforcementGuard`, 두 검사 모두). - -## 허용하는 트랜잭션 모양 (Allowed transactional shapes) - -| 유스케이스 모양 | `transactionMode` | TransactionPort 호출 | 언제 | -|---|---|---|---| -| 쓰기 command | `WRITE` | `tx.inWrite(...)` | `CommandUseCase`의 기본. | -| 물리 루트 쓰기 command | `WRITE` | `tx.inRootWrite(...)` | 바깥 트랜잭션이 없음을 증명하고 커밋 뒤에 결과를 내놓아야 하는 조율일 때만. | -| 읽기 전용 query | `READ_ONLY` | `tx.inRead(...)` | `QueryUseCase`의 기본. | -| outbox·감사·보상 | `REQUIRES_NEW` | `tx.inNew(...)` | 유스케이스가 반드시 호출자와 따로 커밋해야 할 때만. | - -`NESTED`와 `NEVER` 전파는 금지다. -`inRootWrite`는 action이나 `PlatformTransactionManager`를 부르기 전에 실제로 열린 바깥 트랜잭션을 -반드시 거절한다. 루트 전용 동작을 `REQUIRES_NEW`로 흉내 내면 안 된다. -`WRITE_REPOSITORY + WRITE` 유스케이스의 직접 경계 적합성 규칙은 `inWrite`와 `inRootWrite`가 모두 -만족한다. READ와 REQUIRES_NEW의 대응은 계속 서로 배타적이다. - -### 콜백 시그니처 계약 - -`TransactionPort` 콜백은 `Supplier` / `Runnable`이라 checked 예외를 던지지 못한다. Spring -`TransactionCallback`의 제약과 같다. 도메인의 checked 예외는 `RuntimeException` 하위 클래스로 -감싼다(`DomainException extends RuntimeException`). `IOException`은 `UncheckedIOException`으로 -감싼다. `SQLException`은 Spring의 `DataAccessException` 계층이 자동으로 번역한다. - -### `inNew` 풀 크기 제약 - -`inNew`는 새 물리 JDBC 연결을 얻는다. 풀 크기는 반드시 다음을 만족한다. - -``` -hikari.maximumPoolSize >= (concurrent_threads × (1 + max_inNew_depth)) + 1 -``` - -**금지**: 많은 레코드를 도는 반복문 안에서 `tx.inNew(...)`를 부른다 — 풀이 바닥나고 교착이 생길 -수 있다. 레코드를 `inNew` 호출 **하나** 안에서 묶어 처리하거나, 반복문을 트랜잭션 경계 밖으로 뺀다. - -## 멱등성 (KEYED) — feature-rate-limit-idempotency-contract - -`@UseCaseCapability(idempotency = Idempotency.KEYED)`는 **지원한다**. KEYED 유스케이스는 자기 일을 -`dev.caskeleton.application.idempotency.IdempotencyExecutor`로 감싼다. 소유자를 안전하게 지키는 -유일한 세대다. V1 `IdempotencyScope`/`tryBegin` API는 없어졌다. - -- **범위(scope)**: 호출자가 `IdempotencyScopeDigest`를 넘긴다. principal + client key + operation - code의 버전 있는 HMAC이고, executor가 받기 전에 계산한다. 원본 `Idempotency-Key`는 이 계층에도 - store에도 닿지 않는다. -- **store**: `IdempotencyStorePort`. `app.capabilities.idempotency.provider`로 고른 provider 정확히 - 하나가 내놓는다(`redis` → `cache-redis`, `postgresql` → `persistence-jpa`, 기본값 `disabled`). - 운영에서 메모리 저장소는 금지다. -- **executor**: `composition:idempotency`의 `IdempotencyAutoConfiguration`이 `IdempotencySettings`로 - 한 번 만든다(처리 lease 30s, 재생 TTL `APP_IDEMPOTENCY_TTL` 24h ≤72h이고 lease보다 짧지 않다, 실패 - 보존 24h이고 재생 TTL보다 짧지 않다). 유스케이스나 서비스 자신의 설정에서 만들지 않는다. -- action은 `IdempotentAction.Outcome`(`Success` / `RetryableNoEffect` / `EffectUnknown`)을 - 돌려준다. 던진 예외는 효과를 모름(effect-unknown)으로 센다. 처리 중이면 409 - `IDEMPOTENT_IN_FLIGHT`, fingerprint(SHA-256)가 다르면 422 `IDEMPOTENT_REQUEST_MISMATCH`다. - `IdempotencyUnavailableException`과 `IdempotencyRecoveryRequiredException`은 store가 결과를 - 증명하지 못했다는 뜻이니 무턱대고 다시 시도하지 않는다. -- 모든 store는 처리 lease가 끝난 실행에 `RecoveryRequired`로 답하고 그 실행을 넘겨받지 않는다. - 넘겨받는 것은 시작하지 않은 claim이나 다시 시도할 수 있는 실패뿐이다. 이 답은 레코드를 가진 - 쪽에게 남긴다: 가진 쪽이 늦게 보낸 첫 `complete`/`markFailed`는 기록한다. lease가 끝난 것은 - 갱신하지 않고, lease가 끝난 claim은 시작하지 않는다. 둘 다 `NOT_OWNER`가 아니라 `LEASE_EXPIRED`로 - 답하고, executor는 거절된 시작을 「적용 안 됨」으로 바꾼다(소유자 결정 2026-11-04). 레코드는 - lease에 재생 TTL을 더한 만큼 산다. `IdempotencyStoreContract`가 Redis와 PostgreSQL을 실제 서버에서 - 둘 모두에 맞춘다. 메모리 fake는 시간을 모델링하지 않으니 계약 중 시간이 없는 경우만 돈다. -- 모든 전이는 그 레코드를 claim한 operation을 이름으로 댄다(`IdempotencyOwner.claimOperationId()`). - 다른 operation이면 모든 store에서 `OPERATION_CONFLICT`이고 아무것도 바꾸지 않는다. owner token을 - 다른 operation으로 가져온 조회도 같다(소유자 결정 2026-11-06). -- 이미 적용된 전이는 그것을 적용한 handle에게만 「already …」로 확인해 준다. 그 handle은 그 전이로 - 옮겨 간, 한 revision 뒤의 레코드다. 다른 handle은 모두 `NOT_OWNER`다. 넘겨받기 전의 같은 시도의 - handle도, 갱신을 적용한 handle로 하는 시작도 그렇다. 놓아준 handle로 하는 시작은 store가 놓아준 - 레코드를 남기느냐에 따라 `ABSENT`나 `NOT_OWNER`다(소유자 결정 2026-11-06, - `IdempotencyStoreContract`). -- 적용한 handle이 다른 disposition으로 `markFailed`를 다시 보내면 `OPERATION_CONFLICT`이고 기록된 - 실패가 남는다. retention만 다르면 `ALREADY_MARKED_SAME_OPERATION`이고 처음 retention이 남는다 — - retention은 완료의 재생 TTL처럼 비교하지 않는다(소유자 결정 2026-11-07). - -예전 ArchUnit 동결 규칙 `inbound_port_implementations_do_not_declare_keyed_idempotency`와 그 fixture는 -이 브랜치가 병합될 때 지웠다. - -## 읽기·query 경로 (feature-application-query-bypass-contract) - -읽기 쪽에는 똑같이 유효한 모양이 둘 있다. 읽기마다 고르고, 하나를 강요하지 않는다. - -| 모양 | 돌려주는 것 | 언제 | 어떻게 | -|---|---|---|---| -| **aggregate를 거쳐서**(단순 읽기의 기본) | `*Repository` 포트로 받은 도메인 aggregate | 읽기 모양 == 쓰기 aggregate **이고** aggregate가 최소 불변식 경계일 때(지연 컬렉션이 필요 없음) | `QueryUseCase` → repository 포트 → `Order` | -| **projection (CQRS-lite)** | `*QueryPort`로 받은 애플리케이션 계층 projection DTO | 읽기 모양 ≠ 쓰기, 또는 aggregate 수화·지연 컬렉션 join을 건너뛰려 할 때 | `QueryUseCase` → `*QueryPort` → `OrderSummary`(record). query는 JPQL `SELECT new` / JdbcTemplate | - -- **순수성 가드레일(core, 기계로 강제):** 단순 이름이 `QueryPort`로 끝나는 읽기 포트는 반드시 - 애플리케이션 계층 projection DTO만 돌려준다 — 도메인 aggregate, JPA 엔티티, web 타입은 **제네릭 - 타입 인자를 거쳐서도**(`List`) 안 된다. ArchUnit - `QUERY_PORTS_DO_NOT_LEAK_DOMAIN_JPA_OR_WEB_TYPES`가 강제한다. projection 사용 자체는 강요된 기본이 - 아니라 **선택**이다. -- **엄격한 절차:** 모든 읽기는 `QueryUseCase` bean을 거친다. web → 읽기 포트로 바로 가는 얇은 - 경로는 없다. 그런 경로는 필수인 `@UseCaseCapability` 적합성 검사를 건너뛴다. -- **트랜잭션:** 읽기의 기본은 `TransactionPort.inRead`다. 트랜잭션 없는(autocommit) 읽기는 - `spring.jpa.open-in-view=false`가 확인됐고 **그리고** 읽기가 projection만 쓰고(지연 접근 없음) - **그리고** 문장 하나일 때만 고를 수 있다. 아니면 `inRead`를 쓴다. -- **capability:** repository를 쓰는 projection 읽기도 `repositoryAccess = READ_REPOSITORY`다. - 「projection이냐 aggregate냐」는 돌려주는 *모양* 축이고, repository 접근 *수준* 축과 따로다 — 새 - enum이 없다. outbound HTTP 읽기(repository 없음)는 `RepositoryAccess.NONE`이다. -- 물리적으로 따로 둔 읽기 저장소를 쓰는 완전한 CQRS는 범위 밖이다. 올려서 정할 일이다. - -## ArchUnit 가드레일(강제됨) - -- `APPLICATION_DOES_NOT_DEPEND_ON_ADAPTERS_OR_TRANSPORT` -- `APPLICATION_DOES_NOT_USE_SPRING_TRANSACTIONAL_ANNOTATION` -- `APPLICATION_DOES_NOT_DEPEND_ON_APPLICATION_CONTEXT` -- `APPLICATION_HAS_NO_DIAGNOSTIC_FRAMEWORK` -- `INBOUND_PORT_IMPLEMENTATIONS_END_WITH_USE_CASE` -- `INBOUND_PORT_IMPLEMENTATIONS_DECLARE_CAPABILITY` -- `QUERY_PORTS_DO_NOT_LEAK_DOMAIN_JPA_OR_WEB_TYPES`(`*QueryPort` 반환 순수성) - -## 테스트 - -```bash -cd src -./gradlew :application-core:test -./gradlew :app-bootstrap:architectureTest -``` - -위 메시징 타입은 semantic contract R1까지만 세운다. JSON Schema 검증, Kafka 발행, durable outbox -영속, 그 밖의 메시징 R2 capability를 주장하지 않는다. +@AGENTS.md diff --git a/src/application-core/README.md b/src/application-core/README.md index 026f6593..5aa32fe9 100644 --- a/src/application-core/README.md +++ b/src/application-core/README.md @@ -3,7 +3,7 @@ 애플리케이션 유스케이스 계층. 패키지 루트: `dev.caskeleton.application`. 허용/금지 의존, 유스케이스 형태, 트랜잭션 모드, 명명 규칙 같은 **모듈 규칙**은 -[CLAUDE.md](CLAUDE.md) 가 SSOT 다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를 +[AGENTS.md](AGENTS.md) 가 SSOT 다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를 모아둔 참조용 기록이다 — 코드를 읽다 "왜 이렇게 했나"가 궁금할 때 본다. 아래 설명은 별도 추적 ID를 몰라도 읽히도록 결정의 배경과 트레이드오프를 문장으로 풀어 둔다. diff --git a/src/composition/outbox-relay/AGENTS.md b/src/composition/outbox-relay/AGENTS.md new file mode 100644 index 00000000..1f890d5f --- /dev/null +++ b/src/composition/outbox-relay/AGENTS.md @@ -0,0 +1,19 @@ +# composition:outbox-relay + +- 모듈 ID `composition-outbox-relay`, Gradle 경로 `:composition:outbox-relay`. registry 정본: + `src/config/architecture/modules.json`. +- 책임: 애플리케이션의 outbox relay를 조립하고 돌린다. `app.outbox.*`(`OutboxSettings`, 엄격한 + 바인딩)로 `PublishPendingOutboxEventsUseCase`를 손으로 만들고, `OutboxRelayScheduler`(고정 지연 + tick, 메시징 플랫폼의 admission phase보다 위에서 멈추는 `SmartLifecycle`)에서 돌리며, outbox metric + (`OutboxMetrics`: 자기 스레드에서 도는 gauge, relay가 내는 cycle 결과 counter)을 가진다. +- 경계: 포트만 이름으로 댄다 — `OutboxStorePort`, `OutboxMessagePublishPort`, + `OutboxRelayFailureReportPort`, `TransactionPort`. 모듈 타입은 대지 않으니 persistence나 messaging + 줄을 지우면 relay도 빠진다. 업무 규칙, SQL, broker 타입이 없다. relay 유스케이스는 bean이 아니다 + (`@SystemInvoked`, 권한 검사 없음). 허용 edge는 registry 항목에서만 온다. +- 기동 거절은 여기 있다. 설정과 포트가 만나는 곳이 여기뿐이기 때문이다: 최악의 경우 + (`batch-size` × 발행 포트의 `longestAttempt`)가 `in-flight-timeout`에 닿는 batch는 기동에 실패한다. +- 시험: `./gradlew :composition:outbox-relay:check`. 종료 순서는 플랫폼 자신의 phase 상수에 맞춰 + 고정한다(`OutboxRelayShutdownOrderTest`). relay → bridge → 실제 Kafka로 가는 끝에서 끝까지 경로는 + `:adapter:outbound:messaging-kafka:messagingKafkaRelayIntegrationTest`다. +- 설계와 버린 대안: `README.md`. 운영: `docs/runbooks/outbox-publish-failed.md`, + `docs/runbooks/outbox-dead-letter.md`. diff --git a/src/composition/outbox-relay/CLAUDE.md b/src/composition/outbox-relay/CLAUDE.md index 1f890d5f..43c994c2 100644 --- a/src/composition/outbox-relay/CLAUDE.md +++ b/src/composition/outbox-relay/CLAUDE.md @@ -1,19 +1 @@ -# composition:outbox-relay - -- 모듈 ID `composition-outbox-relay`, Gradle 경로 `:composition:outbox-relay`. registry 정본: - `src/config/architecture/modules.json`. -- 책임: 애플리케이션의 outbox relay를 조립하고 돌린다. `app.outbox.*`(`OutboxSettings`, 엄격한 - 바인딩)로 `PublishPendingOutboxEventsUseCase`를 손으로 만들고, `OutboxRelayScheduler`(고정 지연 - tick, 메시징 플랫폼의 admission phase보다 위에서 멈추는 `SmartLifecycle`)에서 돌리며, outbox metric - (`OutboxMetrics`: 자기 스레드에서 도는 gauge, relay가 내는 cycle 결과 counter)을 가진다. -- 경계: 포트만 이름으로 댄다 — `OutboxStorePort`, `OutboxMessagePublishPort`, - `OutboxRelayFailureReportPort`, `TransactionPort`. 모듈 타입은 대지 않으니 persistence나 messaging - 줄을 지우면 relay도 빠진다. 업무 규칙, SQL, broker 타입이 없다. relay 유스케이스는 bean이 아니다 - (`@SystemInvoked`, 권한 검사 없음). 허용 edge는 registry 항목에서만 온다. -- 기동 거절은 여기 있다. 설정과 포트가 만나는 곳이 여기뿐이기 때문이다: 최악의 경우 - (`batch-size` × 발행 포트의 `longestAttempt`)가 `in-flight-timeout`에 닿는 batch는 기동에 실패한다. -- 시험: `./gradlew :composition:outbox-relay:check`. 종료 순서는 플랫폼 자신의 phase 상수에 맞춰 - 고정한다(`OutboxRelayShutdownOrderTest`). relay → bridge → 실제 Kafka로 가는 끝에서 끝까지 경로는 - `:adapter:outbound:messaging-kafka:messagingKafkaRelayIntegrationTest`다. -- 설계와 버린 대안: `README.md`. 운영: `docs/runbooks/outbox-publish-failed.md`, - `docs/runbooks/outbox-dead-letter.md`. +@AGENTS.md diff --git a/src/domain-core/AGENTS.md b/src/domain-core/AGENTS.md new file mode 100644 index 00000000..70bf470b --- /dev/null +++ b/src/domain-core/AGENTS.md @@ -0,0 +1,38 @@ +# domain-core — 순수 도메인 계층 + +## 등록 정보 + +- 모듈 ID: `domain-core` +- Gradle 경로: `:domain-core` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :domain-core:test --console=plain` +- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. +- registry 정본: `src/config/architecture/modules.json`. + +패키지 루트: `dev.caskeleton.domain`. + +코드 주석에서 덜어낸 **설계 결정의 근거**는 [README.md](README.md) 가 모아둔다 (이 문서는 모듈 규칙 SSOT). + +## 책임 + +- 업무 개념, 엔티티, 값 객체, enum, 도메인 이벤트, 도메인 서비스. +- 이 참조 구현이 아직 도메인 소유 영속 계약을 두는 곳의 repository 포트. +- 도메인 불변식과 핵심 규칙. + +## 허용 + +- Java 표준 라이브러리. +- 값만 담은 공용 운영 타입은 정말 필요할 때만. + +## 금지 + +- Spring 애너테이션. +- JPA 애너테이션. +- Servlet·HTTP 타입. +- 어댑터, application, bootstrap, 표현 계층 DTO 의존. + +## 테스트 + +```bash +cd src +./gradlew :domain-core:test +``` diff --git a/src/domain-core/CLAUDE.md b/src/domain-core/CLAUDE.md index 70bf470b..43c994c2 100644 --- a/src/domain-core/CLAUDE.md +++ b/src/domain-core/CLAUDE.md @@ -1,38 +1 @@ -# domain-core — 순수 도메인 계층 - -## 등록 정보 - -- 모듈 ID: `domain-core` -- Gradle 경로: `:domain-core` -- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :domain-core:test --console=plain` -- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. -- registry 정본: `src/config/architecture/modules.json`. - -패키지 루트: `dev.caskeleton.domain`. - -코드 주석에서 덜어낸 **설계 결정의 근거**는 [README.md](README.md) 가 모아둔다 (이 문서는 모듈 규칙 SSOT). - -## 책임 - -- 업무 개념, 엔티티, 값 객체, enum, 도메인 이벤트, 도메인 서비스. -- 이 참조 구현이 아직 도메인 소유 영속 계약을 두는 곳의 repository 포트. -- 도메인 불변식과 핵심 규칙. - -## 허용 - -- Java 표준 라이브러리. -- 값만 담은 공용 운영 타입은 정말 필요할 때만. - -## 금지 - -- Spring 애너테이션. -- JPA 애너테이션. -- Servlet·HTTP 타입. -- 어댑터, application, bootstrap, 표현 계층 DTO 의존. - -## 테스트 - -```bash -cd src -./gradlew :domain-core:test -``` +@AGENTS.md diff --git a/src/domain-core/README.md b/src/domain-core/README.md index d89d7f84..9ab2a4ce 100644 --- a/src/domain-core/README.md +++ b/src/domain-core/README.md @@ -2,7 +2,7 @@ 순수 도메인 계층 모듈. 패키지 루트: `dev.caskeleton.domain`. -허용/금지 의존, 책임 범위, 테스트 명령 같은 **모듈 규칙**은 [CLAUDE.md](CLAUDE.md) 가 SSOT 다. +허용/금지 의존, 책임 범위, 테스트 명령 같은 **모듈 규칙**은 [AGENTS.md](AGENTS.md) 가 SSOT 다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를 모아둔 참조용 기록이다 — 코드를 읽다 "왜 이렇게 했나"가 궁금할 때 본다. 플랜/스펙 추적용 ID는 더 이상 코드 주석에 두지 않고, 그 근거를 아래에 쉬운 말로 풀어 둔다. diff --git a/src/platforms/grpc-advanced/AGENTS.md b/src/platforms/grpc-advanced/AGENTS.md new file mode 100644 index 00000000..6121029a --- /dev/null +++ b/src/platforms/grpc-advanced/AGENTS.md @@ -0,0 +1,88 @@ +# grpc-advanced — 고급 gRPC capability의 지역 정본 + +이 문서는 `grpc-advanced:*` family의 **지역 정본(local authority)**이다. leaf 목록·gradle path·허용 의존성은 +`src/config/architecture/modules.json`이 SSOT다. 루트 `AGENTS.md`와 충돌하면 +루트가 이긴다. + +이 family는 Stable gRPC 플랫폼(`grpc:*`)이 **의도적으로 제외한** 능력들을 담는다. 별도 디렉터리와 +별도 Gradle prefix인 이유는 하나다: "Stable starter가 advanced module을 참조하면 build가 실패한다"는 +불변 조건을 registry의 `allowed_dependencies`만으로 기계 검증할 수 있게 하기 위해서다. + +## 의존 방향 + +```text +grpc-advanced:* → grpc:* (허용) +grpc:* → grpc-advanced:* (금지 — registry가 거부한다) +``` + +`grpc-spring-boot-starter`의 registry 엔트리에는 어떤 advanced id도 없다. +`verifyCleanArchitectureDependencies`가 build time에 이 규칙을 강제한다. runtime 검사는 없다. + +### 공용 다이제스트 헬퍼를 복사해 두는 이유 + +`grpc-advanced`(`GrpcDiagnosticsRedactor`)는 SHA-256 계산을 자기 안에 둔다. 의존 방향이 +`grpc-advanced:* → grpc:*`로 닫혀 있고 `shared-contract` edge가 없는 것은 의도다. `grpc/AGENTS.md`의 +같은 절과 이유가 같다(vendored 플랫폼, messaging family와 같은 배치). + +## Capability grade와 feature flag + +capability마다 별도 flag를 갖는다. 하나의 "advanced" 스위치로 묶지 않는 이유는, gRPC-Web을 켜는 +결정(프록시 하나)과 xDS를 켜는 결정(control plane과 그 장애 모드 전체)이 같은 결정이 아니기 +때문이다. 하나의 스위치는 두 번째 결정을 실수로 내리게 만든다. + +| grade | 시작 가능 | production 추가 승인 | +| --- | --- | --- | +| `ADVANCED_STABLE` | O | 불필요 | +| `EXPERIMENTAL` | O | **필요** | +| `WATCH` | X (추적만) | — | +| `DISABLED` | X | — | + +property key는 `app.grpc.advanced..enabled`이고 전부 기본 off다. +`GrpcAdvancedModuleGuard`가 세 조건(flag 미설정 / grade가 시작 불가 / production 승인 없음)을 +구분해서 거부하며, 세 경우의 조치가 다르므로 메시지도 다르다. + +## Leaf별 담당 capability + +| leaf | 패키지(`dev.caskeleton.grpc.advanced.*`) | capability | +| --- | --- | --- | +| `grpc-advanced` | `bootstrap` | capability grade, feature flag, module guard, capability별 promotion gate | +| `grpc-advanced` | `edition` | Protobuf Edition 2024 opt-in lane, Edition 2026 watch lane | +| `grpc-advanced` | `streaming` | client streaming(session/dedup/checkpoint), bidi(dual sequence), manual flow control | +| `grpc-advanced` | `resilience`·`discovery`·`xds` | read-only hedging, custom name resolver SPI, custom load balancer SPI, proxyless xDS | +| `grpc-advanced` | `diagnostics` | Channelz/CSDS 진단 | +| `grpc-advanced-compat` | `web`·`integration`·`reactor`·`kotlin` | gRPC-Web, Spring Integration bridge, Reactor adapter, Kotlin coroutine 취소 bridge | + +`grpc-advanced-compat`만 따로 있는 이유는 Reactor·Spring Integration이라는 실제 의존성 경계다. 나머지 +다섯 capability는 framework 의존이 없어 한 leaf에 있다(2026-09-28까지는 leaf 다섯 개). capability별 +독립은 leaf 경계가 아니라 capability flag와 promotion 레코드가 보장한다. 참조 Envoy 설정은 jar에 싣지 +않는 테스트 fixture(`grpc-advanced-compat/src/test/resources/envoy/envoy.yaml`)다. + +## Promotion은 capability별로 독립이다 + +승격 증거는 capability마다 따로 판단한다. 공유 증거였다면 하나를 승격할 때 같은 시점에 측정된 다른 +것들이 함께 승격된다. 이 규칙을 코드로 옮겨 두었던 `GrpcAdvancedPromotionGate`는 자기 테스트 말고 +호출처가 없어 2026-09-25 리뷰 후속 작업에서 삭제했다. 지금은 `docs/runbooks/grpc-advanced-capabilities.md`의 +리뷰 규칙이다. + +승격 문턱은 두 개다: `ADVANCED_STABLE`은 7일 soak + 전체 증거, Stable default는 30일 soak. 두 번째가 +더 높은 이유는 모든 배포가 그 의존성과 장애 모드를 갖게 되기 때문이다. + +## 이 저장소에서 검증할 수 없는 것 + +capability별로 필요한 실제 인프라가 이 저장소에 없다. + +- `grpc-web` → gRPC-Web 프록시 +- `servlet-compat` → Servlet 컨테이너 +- `xds` → 중지 가능한 xDS control plane +- `kotlin` → Kotlin 툴체인 + +인프라 없이 도는 suite는 통과하면서 아무것도 증명하지 않으므로, suite가 없는 것보다 나쁘다. +이 사실을 상수로 반환하던 gate 클래스(`GrpcKotlinCompatibilityGate`, `GrpcAdvancedInfrastructureTestkit` +등)는 2026-09-25 삭제됐다 — 지원 여부는 이 문서와 support matrix가 적는다. + +## 금지 + +- Stable leaf(`grpc:*`)가 이 family를 참조하는 것. +- capability grade 없이, 또는 flag 없이 advanced 코드 경로를 실행하는 것. +- `WATCH` capability를 스키마 소스로 사용하는 것. +- 실제 인프라 없이 실행한 suite를 promotion evidence로 인용하는 것. diff --git a/src/platforms/grpc-advanced/CLAUDE.md b/src/platforms/grpc-advanced/CLAUDE.md index d78e9d8d..43c994c2 100644 --- a/src/platforms/grpc-advanced/CLAUDE.md +++ b/src/platforms/grpc-advanced/CLAUDE.md @@ -1,88 +1 @@ -# grpc-advanced — 고급 gRPC capability의 지역 정본 - -이 문서는 `grpc-advanced:*` family의 **지역 정본(local authority)**이다. leaf 목록·gradle path·허용 의존성은 -`src/config/architecture/modules.json`이 SSOT다. Root 정책(`CLAUDE.md` / `AGENTS.md`)과 충돌하면 -root가 이긴다. - -이 family는 Stable gRPC 플랫폼(`grpc:*`)이 **의도적으로 제외한** 능력들을 담는다. 별도 디렉터리와 -별도 Gradle prefix인 이유는 하나다: "Stable starter가 advanced module을 참조하면 build가 실패한다"는 -불변 조건을 registry의 `allowed_dependencies`만으로 기계 검증할 수 있게 하기 위해서다. - -## 의존 방향 - -```text -grpc-advanced:* → grpc:* (허용) -grpc:* → grpc-advanced:* (금지 — registry가 거부한다) -``` - -`grpc-spring-boot-starter`의 registry 엔트리에는 어떤 advanced id도 없다. -`verifyCleanArchitectureDependencies`가 build time에 이 규칙을 강제한다. runtime 검사는 없다. - -### 공용 다이제스트 헬퍼를 복사해 두는 이유 - -`grpc-advanced`(`GrpcDiagnosticsRedactor`)는 SHA-256 계산을 자기 안에 둔다. 의존 방향이 -`grpc-advanced:* → grpc:*`로 닫혀 있고 `shared-contract` edge가 없는 것은 의도다. `grpc/CLAUDE.md`의 -같은 절과 이유가 같다(vendored 플랫폼, messaging family와 같은 배치). - -## Capability grade와 feature flag - -capability마다 별도 flag를 갖는다. 하나의 "advanced" 스위치로 묶지 않는 이유는, gRPC-Web을 켜는 -결정(프록시 하나)과 xDS를 켜는 결정(control plane과 그 장애 모드 전체)이 같은 결정이 아니기 -때문이다. 하나의 스위치는 두 번째 결정을 실수로 내리게 만든다. - -| grade | 시작 가능 | production 추가 승인 | -| --- | --- | --- | -| `ADVANCED_STABLE` | O | 불필요 | -| `EXPERIMENTAL` | O | **필요** | -| `WATCH` | X (추적만) | — | -| `DISABLED` | X | — | - -property key는 `app.grpc.advanced..enabled`이고 전부 기본 off다. -`GrpcAdvancedModuleGuard`가 세 조건(flag 미설정 / grade가 시작 불가 / production 승인 없음)을 -구분해서 거부하며, 세 경우의 조치가 다르므로 메시지도 다르다. - -## Leaf별 담당 capability - -| leaf | 패키지(`dev.caskeleton.grpc.advanced.*`) | capability | -| --- | --- | --- | -| `grpc-advanced` | `bootstrap` | capability grade, feature flag, module guard, capability별 promotion gate | -| `grpc-advanced` | `edition` | Protobuf Edition 2024 opt-in lane, Edition 2026 watch lane | -| `grpc-advanced` | `streaming` | client streaming(session/dedup/checkpoint), bidi(dual sequence), manual flow control | -| `grpc-advanced` | `resilience`·`discovery`·`xds` | read-only hedging, custom name resolver SPI, custom load balancer SPI, proxyless xDS | -| `grpc-advanced` | `diagnostics` | Channelz/CSDS 진단 | -| `grpc-advanced-compat` | `web`·`integration`·`reactor`·`kotlin` | gRPC-Web, Spring Integration bridge, Reactor adapter, Kotlin coroutine 취소 bridge | - -`grpc-advanced-compat`만 따로 있는 이유는 Reactor·Spring Integration이라는 실제 의존성 경계다. 나머지 -다섯 capability는 framework 의존이 없어 한 leaf에 있다(2026-09-28까지는 leaf 다섯 개). capability별 -독립은 leaf 경계가 아니라 capability flag와 promotion 레코드가 보장한다. 참조 Envoy 설정은 jar에 싣지 -않는 테스트 fixture(`grpc-advanced-compat/src/test/resources/envoy/envoy.yaml`)다. - -## Promotion은 capability별로 독립이다 - -승격 증거는 capability마다 따로 판단한다. 공유 증거였다면 하나를 승격할 때 같은 시점에 측정된 다른 -것들이 함께 승격된다. 이 규칙을 코드로 옮겨 두었던 `GrpcAdvancedPromotionGate`는 자기 테스트 말고 -호출처가 없어 2026-09-25 리뷰 후속 작업에서 삭제했다. 지금은 `docs/runbooks/grpc-advanced-capabilities.md`의 -리뷰 규칙이다. - -승격 문턱은 두 개다: `ADVANCED_STABLE`은 7일 soak + 전체 증거, Stable default는 30일 soak. 두 번째가 -더 높은 이유는 모든 배포가 그 의존성과 장애 모드를 갖게 되기 때문이다. - -## 이 저장소에서 검증할 수 없는 것 - -capability별로 필요한 실제 인프라가 이 저장소에 없다. - -- `grpc-web` → gRPC-Web 프록시 -- `servlet-compat` → Servlet 컨테이너 -- `xds` → 중지 가능한 xDS control plane -- `kotlin` → Kotlin 툴체인 - -인프라 없이 도는 suite는 통과하면서 아무것도 증명하지 않으므로, suite가 없는 것보다 나쁘다. -이 사실을 상수로 반환하던 gate 클래스(`GrpcKotlinCompatibilityGate`, `GrpcAdvancedInfrastructureTestkit` -등)는 2026-09-25 삭제됐다 — 지원 여부는 이 문서와 support matrix가 적는다. - -## 금지 - -- Stable leaf(`grpc:*`)가 이 family를 참조하는 것. -- capability grade 없이, 또는 flag 없이 advanced 코드 경로를 실행하는 것. -- `WATCH` capability를 스키마 소스로 사용하는 것. -- 실제 인프라 없이 실행한 suite를 promotion evidence로 인용하는 것. +@AGENTS.md diff --git a/src/platforms/grpc/AGENTS.md b/src/platforms/grpc/AGENTS.md new file mode 100644 index 00000000..2dd48896 --- /dev/null +++ b/src/platforms/grpc/AGENTS.md @@ -0,0 +1,192 @@ +# grpc — gRPC 플랫폼 family의 지역 정본 + +이 문서는 `grpc:*` family의 **지역 정본(local authority)**이다. gRPC platform은 기본 application build와 분리된 +`src/platforms/optional-build` build가 소유한다. 여기서 정하는 것은 family별 framework 규칙, 증거 등급, +Stable 범위의 경계와 application에 채택될 때 필요한 계약이다. + +루트 `AGENTS.md`와 충돌하면 루트가 이긴다. + +이 family는 Clean Architecture의 계층이 아니라 **벤더드 RPC 플랫폼**이다 — `messaging:*`와 같은 +자리에 있고 같은 이유로 있다. 자기 API(port)와 adapter와 조립 경계(starter)를 가지며, 애플리케이션은 +`adapter:inbound:grpc`를 통해 라이브러리로서 도달한다. + +설계 근거와 원본 계획 대비 deviation은 +[docs/design/2026-08-30-grpc-platform-adaptation-design.md](../../../docs/design/2026-08-30-grpc-platform-adaptation-design.md)가 SSOT다. + +## Family와 framework 규칙 + +leaf의 정확한 id는 registry에서 읽는다. + +| Family | 역할 | 허용 framework | +| --- | --- | --- | +| `grpc-core-api` | 식별자, method policy, 실행 증거, 실패 모델, deadline, request context, operation ledger port | **Java stdlib만.** io.grpc / Spring / protobuf / DB 타입 금지 | +| `grpc-contract` | `.proto` 스키마 소스(`src/main/proto`)와 protoc 생성 message. lint/breaking은 Buf(`buf.yaml`, CI job `grpc-proto-buf`) | `protobuf-java`(생성 코드 runtime)만. 규칙을 Java로 재구현하지 않는다 | +| `grpc-runtime` | policy(validation, context, status/rich error, TLS/credential, deadline/cancellation, retry, idempotency, streaming, size/compression) · server(typed service adapter SPI, interceptor 순서, Netty profile) · client(named channel, runtime generation, typed stub factory) · discovery(Static/DNS, pick_first/round_robin, Kubernetes routing) · admin(health, reflection, drain, policy snapshot) | `io.grpc:grpc-api`, `grpc-stub`. Spring·Netty 자체 금지 — Netty profile은 설정 모델이다 | +| `grpc-observability` | bounded metric/trace convention | `io.micrometer:micrometer-core`만 | +| `grpc-operation-ledger-jpa` | mutation idempotency의 durable 저장 | `jakarta.persistence`, `spring-data-jpa`. **port는 core-api에 있다** | +| `grpc-spring-boot-starter` | 조립 경계, typed properties, startup validator | Spring Boot autoconfigure. 여기서만 | +| `grpc-testkit` | in-process / 실제 Netty / fault / performance 인증 | io.grpc netty-shaded, inprocess. production leaf가 의존하지 않는다 | + +`grpc-core-api`가 io.grpc를 이름조차 부르지 않는다는 것이 이 family의 핵심 제약이다. 실행 증거와 +실패 모델은 "전송이 무엇을 했는가"를 기술하는 계약이고, 그 계약 안에 전송 타입이 들어가면 계약이 +전송의 일부가 된다. `GrpcStatusCode`가 io.grpc의 코드를 미러링하는 이유가 이것이고, 양방향 번역은 +`grpc-runtime`의 `GrpcStatusMapping`이 단독으로 소유한다. + +기본 전송 한도(메시지 1 MiB, metadata 8 KiB)는 `grpc-core-api`의 `GrpcTransportLimits` 한 곳에 있고, +server profile·named channel profile·method size profile·method policy 기본값·metadata budget이 모두 +그 상수를 쓴다. `GrpcPlatformStartupValidator`는 method의 inbound 한도가 server profile 한도보다 크면 +기동을 거부한다. + +`.proto`의 proto 조직 이름은 `caskeleton`이다(`package caskeleton.grpc.common.v1`, 생성 Java 패키지 +`caskeleton.grpc.common.v1.generated` — 손으로 쓴 `dev.caskeleton`과 겹치지 않는다). 템플릿을 재사용할 +때 바꾸는 방법은 `AGENTS.md` 「템플릿 재사용 체크리스트」에 있다. + +### 공용 다이제스트 헬퍼를 복사해 두는 이유 + +`grpc-runtime`(`GrpcRequestFingerprint`, `GrpcResumeTokenCodec`)은 SHA-256·HMAC-SHA256 계산을 자기 +안에 둔다. 템플릿의 `shared-contract` `digest/Sha256`·`HmacSha256`을 쓰지 않는 것은 의도다. 이 +family는 optional build에 있는 vendored 플랫폼이고 registry edge는 `grpc:*` 안에서만 닫힌다(위 표). +`shared-contract` edge를 주면 플랫폼이 템플릿 계약 leaf에 묶여 따로 떼어 쓸 수 없게 된다 — messaging +family가 같은 이유로 고른 배치(2026-08-14 messaging 모듈 리뷰 뒤 소유자가 정함)와 같다. 복사본을 고칠 때는 `shared-contract`의 정본과 +같은 규칙인지 함께 본다. + +## 증거 등급 — testkit이 하나의 leaf인 이유 + +원본 계획은 testkit을 core/in-process/netty/fault 4개 모듈로 쪼갠다. 목적은 "in-process 결과를 +네트워크 증거로 오해하지 않게 한다"이고, 이 저장소는 그 목적을 모듈 경계가 아니라 **strict test +lane**으로 표현한다(`ca.strict-test-lane`: lane은 아무것도 실행하지 않으면 실패하고 up-to-date +결과를 제공하지 않는다). + +`grpc-testkit`의 네 lane과 그 태그: + +| lane | 태그 | 증명하는 것 | +| --- | --- | --- | +| `grpcInProcessContractTest` | `grpc-inprocess` | adapter, interceptor 순서, status, validation, idempotency replay | +| `grpcNettyContractTest` | `grpc-netty` | 실제 소켓 위의 HTTP/2, TLS/mTLS, metadata·message hard limit, GOAWAY, drain | +| `grpcFaultTest` | `grpc-fault` | 각 증거 경계에서의 연결 손실, completion unknown, partial stream | +| `grpcPerformanceTest` | `grpc-performance` | latency percentile, saturation, drain budget | + +lane 분리만으로는 리포트가 잘못된 run을 인용하는 것을 막지 못하므로 `GrpcEvidenceGrade`가 런타임 +체크로 이를 붙든다: `CONTRACT` 등급으로 `tls`를 주장하면 예외다. + +**performance lane은 기본 `test`에서 제외된다**(leaf `build.gradle`). 공유 CI runner에서의 측정은 +release path의 flaky gate가 되고, flaky gate는 꺼진다. + +## Stable 범위 + +Stable RPC 유형은 **Unary와 Server Streaming뿐**이다. Client Streaming, Bidirectional Streaming, +hedging, xDS, custom resolver/LB, gRPC-Web, Servlet, Reactor, Kotlin은 전부 `grpc-advanced:*`이며 +capability flag 뒤에 있다. `GrpcPlatformStartupValidator`가 Stable catalog에 streaming method가 +등록되면 startup을 거부한다. + +`grpc-spring-boot-starter`는 어떤 advanced module도 참조하지 않는다. registry의 +`allowed_dependencies`와 `verifyCleanArchitectureDependencies`가 이를 build time에 강제한다. + +## Optional build에 있다는 것의 의미 + +`grpc:*`와 `grpc-advanced:*`는 기본 `ca-skeleton` settings에 include되지 않는다. 따라서 일반 +`:app-bootstrap:build`는 이 project들을 configure하지 않는다(목록은 registry의 `"build": "optional-grpc"`). 플랫폼 자체는 +`./gradlew -p platforms/optional-build ci`로 검증하고, application runtime에 실제 채택하려면 composition root가 +명시적으로 dependency를 가져오는 별도 변경이 필요하다. + +런타임 포함 여부와 qualification은 별개다. in-process·Netty·fault lane이 통과해도 실제 배포 환경의 +soak/performance baseline을 자동으로 의미하지 않는다. 지원 범위는 release gate와 support matrix가 +별도로 정의한다. + +## application이 이 family에 도달하는 경로 + +`messaging:*`가 겪은 bridge 부재(2026-08-14 messaging 모듈 리뷰)를 반복하지 않는 것이 이 family의 목표다. 계약상의 경로는 + +```text +application-owned port → adapter:inbound:grpc (typed service adapter) → :grpc:grpc-runtime SPI +``` + +이고 `GrpcServiceAdapter`가 그 SPI를 소유한다. inbound adapter가 outbound adapter·persistence에 +직접 닿지 않는 규칙은 app-bootstrap ArchUnit(`INBOUND_ADAPTERS_DO_NOT_DEPEND_ON_OUTBOUND_ADAPTERS`)이 +검사한다. 현재 `adapter:inbound:grpc`는 이 family에 의존하지 않는다 — registry의 +`allowed_dependencies`를 보라. 배선은 별도 결정이며, 그때 registry edge와 브리지가 함께 들어간다. +starter가 `operation-ledger-enabled=true`일 때 멱등성 판단 bean을 조립하는 것(03-11)은 이 배선이 아니다 — +starter는 서버를 만들지 않고, 그 bean을 서버에 붙이는 일은 채택하는 쪽의 몫이다(아래 「Durable operation +ledger adoption」). + +## 테스트 명령 + +focused test는 registry의 `gradle_path`에서 파생한다. + +```bash +cd src +./gradlew -p platforms/optional-build :grpc::test --console=plain +./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcInProcessContractTest --console=plain +./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcNettyContractTest --console=plain +./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcFaultTest --console=plain +./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcPerformanceTest --console=plain +``` + +## 금지 + +- `grpc-core-api`에서 io.grpc / Spring / protobuf / JPA 타입 사용. +- Stable leaf에서 `:grpc-advanced:*` 참조. +- `grpc-testkit`을 production leaf가 의존하는 것. +- in-process 결과로 transport capability를 주장하는 것 (`GrpcEvidenceGrade`가 거부한다). +- metric tag에 raw metadata·payload·actor/tenant/object/stream/idempotency 식별자를 넣는 것 + (`GrpcMetricCardinalityPolicy`가 거부한다). + + +### 채택할 때의 관측 게이트 + +`grpc-observability`가 구현한 metric 이름은 **아직 `docs/registries/metrics.yaml`에 등록하지 +않았다**. 이 optional family는 출하하는 런타임 capability가 아니기 때문이다. 채택하면서 저장소의 +`.seconds` / `.total` 단위 이름 규칙에 맞는 registry 항목과 그에 맞는 검증 게이트를 더하기 전에는 그 +이름을 저장소가 인증한 metric처럼 내세우지 않는다. + + +### durable operation 원장 채택 + +`grpc-spring-boot-starter`는 JPA 원장 어댑터를 전이 의존으로 끌어오지 않는다(2026-09-18 리뷰가 찾은 문제). durable +operation 멱등성이 필요한 배포는 `:grpc:grpc-operation-ledger-jpa`를 직접 더하고, +`GrpcOperationLedger` bean(`new JpaGrpcOperationLedger(repository)`)을 정의하고, 그 어댑터의 Flyway +위치 `db/migration/grpc`(V001 테이블, V002 보존 index, V003 claim attempt)를 넣고, 아래 flag를 켠다. +원장을 채택하지 않는 배포는 Spring Data JPA classpath 비용을 내지 않는다. + +| 키 (`app.grpc.platform.*`) | 기본값 | 하는 일 | +| --- | --- | --- | +| `operation-ledger-enabled` | `false` | `true`: starter가 배포의 `GrpcOperationLedger` bean 위에 `GrpcIdempotencyInterceptor`(bean `grpcIdempotencyInterceptor`)와 `GrpcOperationLedgerRetention`(bean `grpcOperationLedgerRetention`)을 조립하고, 원장 bean이 없으면 기동을 거절한다. `false`: 두 bean 모두 없고, `IDEMPOTENCY_KEY_REQUIRED`인 메서드가 있으면 기동을 거절한다 | +| `operation-ledger-claim-ttl` | `5m` | `IN_PROGRESS` claim의 주인이 살아 있다고 믿는 시간. 지나면 같은 요청의 재시도가 claim을 넘겨받는다(`GrpcOperationLedger.reclaimStale`). 키가 필요한 모든 메서드의 deadline보다 길지 않으면 기동에서 거절한다 | +| `operation-ledger-retention` | `24h` | 끝난(`COMMITTED`/`FAILED_TERMINAL`) 레코드를 `GrpcOperationLedgerRetention.purgeExpired`가 지울 수 있게 되기 전까지 두는 시간. `IN_PROGRESS` 행은 지우지 않는다 | + +기본값: 5분 TTL은 원장 계약 시험과 interceptor 시험이 인증한 값이다. unary deadline보다 훨씬 길고, +주인이 죽은 키가 클라이언트의 재시도 인내 안에 풀릴 만큼 짧다. 24시간 보존은 HTTP 멱등성 재생 TTL +(`app.capabilities.idempotency.replay-ttl`)과 같다. 레코드를 지운 뒤 같은 키로 하는 재시도는 새 +operation이므로, 보존 시간은 호출자의 재시도 창보다 길어야 한다. + +이 키들은 `docs/registries/env-keys.yaml`에 없다. optional 빌드는 출하하는 런타임이 아니라서 +`app.grpc.platform.*` 키는 하나도 없다. 조립 루트가 플랫폼을 채택할 때 registry에 들어간다. + +**starter가 interceptor를 조립하는 이유(선택지 (b)), (a)가 아닌 이유.** 2026-11-01 성숙도 리뷰는 +(a)를 제안했다: flag를 지우고 원장 bean이 있는지로 판단한다. 2026-11-03에 (b)를 골랐고 ADR-GRPC-004에 +적었다: flag를 남기고 flag는 말 그대로의 뜻이다 — true이면 판정 함수를 조립하고 그 TTL은 설정에서 +온다. (a)는 거짓 약속을 없앴겠지만 채택하는 쪽마다 같은 조립과 TTL 검증을 손으로 다시 만들게 +했다. (b)는 그것을 한곳에 둔다. interceptor bean에는 일부러 `@ConditionalOnMissingBean`이 없다: +바꿔 넣은 bean은 `operation-ledger-claim-ttl`을 소리 없이 무시하게 된다. 돌고 있는 operation의 +중복은 기다리라고 하지 않고 거절한다(`REJECT_IN_PROGRESS`). 기다렸다가 다시 묻는 선택지는 키가 +필요한 메서드가 그것을 필요로 할 때 키가 된다. + +**서버 배선은 여전히 채택하는 쪽의 몫이고, 따로 정할 일로 남는다.** starter는 서버를 만들지 +않으므로, 판정을 조립한다고 플랫폼이 `adapter:inbound:grpc`에 배선되지는 않는다(위 "배선은 +별도 결정"을 본다). `GrpcIdempotencyInterceptor`는 판정 함수이고 `io.grpc.ServerInterceptor`가 +아니다. 채택하는 쪽은 bean을 타입으로 주입받아 자기 `IDEMPOTENCY` 단계 interceptor +(`GrpcServerInterceptorChain.builder().stage(GrpcServerInterceptorStage.IDEMPOTENCY, ...)`)나 자기 +typed service adapter에서 부른다: 변경 전에 `decide(...)`, 변경의 트랜잭션 안에서 +`recordCommit(...)`, 끝난 실패에 `recordFailure(...)`. 두 기록 호출은 모두 `PROCEED` 판정이 실어 온 +`GrpcClaimToken`을 받는다: claim을 넘겨준 시도의 커밋은 거절되고(그 트랜잭션은 롤백된다) 그 실패는 +무시된다. 그래서 느린 주인이 claim을 가져간 시도를 덮어쓰지 못한다(ADR-GRPC-004). + +**지우기 일정은 채택하는 쪽의 몫이다.** `GrpcOperationLedgerRetention.purgeExpired(now)`는 기한이 지난 +끝난 행을 한계 있는 batch(문장 하나에 500)로 지우고, batch가 덜 차서 돌아오면 멈춘다. starter는 이것을 +예약하지 않는다: scheduler를 가지지 않고 어느 replica가 돌려야 하는지 알 수 없으며, 예약된 bean은 모든 +배포에 task scheduler를 강요하게 된다. 채택하는 쪽이 자기 scheduler에서 부른다(예: 한 시간마다). +지우기가 잠긴 행을 건너뛰므로 여러 replica에서 동시에 돌려도 안전하다. 한 번도 돌리지 않아도 안전하지만 +테이블이 끝없이 커진다. + +커밋은 변경의 트랜잭션 안에서 기록해야 하고 TTL은 키가 필요한 가장 느린 메서드보다 길어야 한다. 두 +이유는 모두 ADR-GRPC-004에 있다. diff --git a/src/platforms/grpc/CLAUDE.md b/src/platforms/grpc/CLAUDE.md index 3e128277..43c994c2 100644 --- a/src/platforms/grpc/CLAUDE.md +++ b/src/platforms/grpc/CLAUDE.md @@ -1,192 +1 @@ -# grpc — gRPC 플랫폼 family의 지역 정본 - -이 문서는 `grpc:*` family의 **지역 정본(local authority)**이다. gRPC platform은 기본 application build와 분리된 -`src/platforms/optional-build` build가 소유한다. 여기서 정하는 것은 family별 framework 규칙, 증거 등급, -Stable 범위의 경계와 application에 채택될 때 필요한 계약이다. - -Root 정책(`CLAUDE.md` / `AGENTS.md`)과 충돌하면 root가 이긴다. - -이 family는 Clean Architecture의 계층이 아니라 **벤더드 RPC 플랫폼**이다 — `messaging:*`와 같은 -자리에 있고 같은 이유로 있다. 자기 API(port)와 adapter와 조립 경계(starter)를 가지며, 애플리케이션은 -`adapter:inbound:grpc`를 통해 라이브러리로서 도달한다. - -설계 근거와 원본 계획 대비 deviation은 -[docs/design/2026-08-30-grpc-platform-adaptation-design.md](../../../docs/design/2026-08-30-grpc-platform-adaptation-design.md)가 SSOT다. - -## Family와 framework 규칙 - -leaf의 정확한 id는 registry에서 읽는다. - -| Family | 역할 | 허용 framework | -| --- | --- | --- | -| `grpc-core-api` | 식별자, method policy, 실행 증거, 실패 모델, deadline, request context, operation ledger port | **Java stdlib만.** io.grpc / Spring / protobuf / DB 타입 금지 | -| `grpc-contract` | `.proto` 스키마 소스(`src/main/proto`)와 protoc 생성 message. lint/breaking은 Buf(`buf.yaml`, CI job `grpc-proto-buf`) | `protobuf-java`(생성 코드 runtime)만. 규칙을 Java로 재구현하지 않는다 | -| `grpc-runtime` | policy(validation, context, status/rich error, TLS/credential, deadline/cancellation, retry, idempotency, streaming, size/compression) · server(typed service adapter SPI, interceptor 순서, Netty profile) · client(named channel, runtime generation, typed stub factory) · discovery(Static/DNS, pick_first/round_robin, Kubernetes routing) · admin(health, reflection, drain, policy snapshot) | `io.grpc:grpc-api`, `grpc-stub`. Spring·Netty 자체 금지 — Netty profile은 설정 모델이다 | -| `grpc-observability` | bounded metric/trace convention | `io.micrometer:micrometer-core`만 | -| `grpc-operation-ledger-jpa` | mutation idempotency의 durable 저장 | `jakarta.persistence`, `spring-data-jpa`. **port는 core-api에 있다** | -| `grpc-spring-boot-starter` | 조립 경계, typed properties, startup validator | Spring Boot autoconfigure. 여기서만 | -| `grpc-testkit` | in-process / 실제 Netty / fault / performance 인증 | io.grpc netty-shaded, inprocess. production leaf가 의존하지 않는다 | - -`grpc-core-api`가 io.grpc를 이름조차 부르지 않는다는 것이 이 family의 핵심 제약이다. 실행 증거와 -실패 모델은 "전송이 무엇을 했는가"를 기술하는 계약이고, 그 계약 안에 전송 타입이 들어가면 계약이 -전송의 일부가 된다. `GrpcStatusCode`가 io.grpc의 코드를 미러링하는 이유가 이것이고, 양방향 번역은 -`grpc-runtime`의 `GrpcStatusMapping`이 단독으로 소유한다. - -기본 전송 한도(메시지 1 MiB, metadata 8 KiB)는 `grpc-core-api`의 `GrpcTransportLimits` 한 곳에 있고, -server profile·named channel profile·method size profile·method policy 기본값·metadata budget이 모두 -그 상수를 쓴다. `GrpcPlatformStartupValidator`는 method의 inbound 한도가 server profile 한도보다 크면 -기동을 거부한다. - -`.proto`의 proto 조직 이름은 `caskeleton`이다(`package caskeleton.grpc.common.v1`, 생성 Java 패키지 -`caskeleton.grpc.common.v1.generated` — 손으로 쓴 `dev.caskeleton`과 겹치지 않는다). 템플릿을 재사용할 -때 바꾸는 방법은 `AGENTS.md` 「템플릿 재사용 체크리스트」에 있다. - -### 공용 다이제스트 헬퍼를 복사해 두는 이유 - -`grpc-runtime`(`GrpcRequestFingerprint`, `GrpcResumeTokenCodec`)은 SHA-256·HMAC-SHA256 계산을 자기 -안에 둔다. 템플릿의 `shared-contract` `digest/Sha256`·`HmacSha256`을 쓰지 않는 것은 의도다. 이 -family는 optional build에 있는 vendored 플랫폼이고 registry edge는 `grpc:*` 안에서만 닫힌다(위 표). -`shared-contract` edge를 주면 플랫폼이 템플릿 계약 leaf에 묶여 따로 떼어 쓸 수 없게 된다 — messaging -family가 같은 이유로 고른 배치(2026-08-14 messaging 모듈 리뷰 뒤 소유자가 정함)와 같다. 복사본을 고칠 때는 `shared-contract`의 정본과 -같은 규칙인지 함께 본다. - -## 증거 등급 — testkit이 하나의 leaf인 이유 - -원본 계획은 testkit을 core/in-process/netty/fault 4개 모듈로 쪼갠다. 목적은 "in-process 결과를 -네트워크 증거로 오해하지 않게 한다"이고, 이 저장소는 그 목적을 모듈 경계가 아니라 **strict test -lane**으로 표현한다(`ca.strict-test-lane`: lane은 아무것도 실행하지 않으면 실패하고 up-to-date -결과를 제공하지 않는다). - -`grpc-testkit`의 네 lane과 그 태그: - -| lane | 태그 | 증명하는 것 | -| --- | --- | --- | -| `grpcInProcessContractTest` | `grpc-inprocess` | adapter, interceptor 순서, status, validation, idempotency replay | -| `grpcNettyContractTest` | `grpc-netty` | 실제 소켓 위의 HTTP/2, TLS/mTLS, metadata·message hard limit, GOAWAY, drain | -| `grpcFaultTest` | `grpc-fault` | 각 증거 경계에서의 연결 손실, completion unknown, partial stream | -| `grpcPerformanceTest` | `grpc-performance` | latency percentile, saturation, drain budget | - -lane 분리만으로는 리포트가 잘못된 run을 인용하는 것을 막지 못하므로 `GrpcEvidenceGrade`가 런타임 -체크로 이를 붙든다: `CONTRACT` 등급으로 `tls`를 주장하면 예외다. - -**performance lane은 기본 `test`에서 제외된다**(leaf `build.gradle`). 공유 CI runner에서의 측정은 -release path의 flaky gate가 되고, flaky gate는 꺼진다. - -## Stable 범위 - -Stable RPC 유형은 **Unary와 Server Streaming뿐**이다. Client Streaming, Bidirectional Streaming, -hedging, xDS, custom resolver/LB, gRPC-Web, Servlet, Reactor, Kotlin은 전부 `grpc-advanced:*`이며 -capability flag 뒤에 있다. `GrpcPlatformStartupValidator`가 Stable catalog에 streaming method가 -등록되면 startup을 거부한다. - -`grpc-spring-boot-starter`는 어떤 advanced module도 참조하지 않는다. registry의 -`allowed_dependencies`와 `verifyCleanArchitectureDependencies`가 이를 build time에 강제한다. - -## Optional build에 있다는 것의 의미 - -`grpc:*`와 `grpc-advanced:*`는 기본 `ca-skeleton` settings에 include되지 않는다. 따라서 일반 -`:app-bootstrap:build`는 이 project들을 configure하지 않는다(목록은 registry의 `"build": "optional-grpc"`). 플랫폼 자체는 -`./gradlew -p platforms/optional-build ci`로 검증하고, application runtime에 실제 채택하려면 composition root가 -명시적으로 dependency를 가져오는 별도 변경이 필요하다. - -런타임 포함 여부와 qualification은 별개다. in-process·Netty·fault lane이 통과해도 실제 배포 환경의 -soak/performance baseline을 자동으로 의미하지 않는다. 지원 범위는 release gate와 support matrix가 -별도로 정의한다. - -## application이 이 family에 도달하는 경로 - -`messaging:*`가 겪은 bridge 부재(2026-08-14 messaging 모듈 리뷰)를 반복하지 않는 것이 이 family의 목표다. 계약상의 경로는 - -```text -application-owned port → adapter:inbound:grpc (typed service adapter) → :grpc:grpc-runtime SPI -``` - -이고 `GrpcServiceAdapter`가 그 SPI를 소유한다. inbound adapter가 outbound adapter·persistence에 -직접 닿지 않는 규칙은 app-bootstrap ArchUnit(`INBOUND_ADAPTERS_DO_NOT_DEPEND_ON_OUTBOUND_ADAPTERS`)이 -검사한다. 현재 `adapter:inbound:grpc`는 이 family에 의존하지 않는다 — registry의 -`allowed_dependencies`를 보라. 배선은 별도 결정이며, 그때 registry edge와 브리지가 함께 들어간다. -starter가 `operation-ledger-enabled=true`일 때 멱등성 판단 bean을 조립하는 것(03-11)은 이 배선이 아니다 — -starter는 서버를 만들지 않고, 그 bean을 서버에 붙이는 일은 채택하는 쪽의 몫이다(아래 「Durable operation -ledger adoption」). - -## 테스트 명령 - -focused test는 registry의 `gradle_path`에서 파생한다. - -```bash -cd src -./gradlew -p platforms/optional-build :grpc::test --console=plain -./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcInProcessContractTest --console=plain -./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcNettyContractTest --console=plain -./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcFaultTest --console=plain -./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcPerformanceTest --console=plain -``` - -## 금지 - -- `grpc-core-api`에서 io.grpc / Spring / protobuf / JPA 타입 사용. -- Stable leaf에서 `:grpc-advanced:*` 참조. -- `grpc-testkit`을 production leaf가 의존하는 것. -- in-process 결과로 transport capability를 주장하는 것 (`GrpcEvidenceGrade`가 거부한다). -- metric tag에 raw metadata·payload·actor/tenant/object/stream/idempotency 식별자를 넣는 것 - (`GrpcMetricCardinalityPolicy`가 거부한다). - - -### 채택할 때의 관측 게이트 - -`grpc-observability`가 구현한 metric 이름은 **아직 `docs/registries/metrics.yaml`에 등록하지 -않았다**. 이 optional family는 출하하는 런타임 capability가 아니기 때문이다. 채택하면서 저장소의 -`.seconds` / `.total` 단위 이름 규칙에 맞는 registry 항목과 그에 맞는 검증 게이트를 더하기 전에는 그 -이름을 저장소가 인증한 metric처럼 내세우지 않는다. - - -### durable operation 원장 채택 - -`grpc-spring-boot-starter`는 JPA 원장 어댑터를 전이 의존으로 끌어오지 않는다(2026-09-18 리뷰가 찾은 문제). durable -operation 멱등성이 필요한 배포는 `:grpc:grpc-operation-ledger-jpa`를 직접 더하고, -`GrpcOperationLedger` bean(`new JpaGrpcOperationLedger(repository)`)을 정의하고, 그 어댑터의 Flyway -위치 `db/migration/grpc`(V001 테이블, V002 보존 index, V003 claim attempt)를 넣고, 아래 flag를 켠다. -원장을 채택하지 않는 배포는 Spring Data JPA classpath 비용을 내지 않는다. - -| 키 (`app.grpc.platform.*`) | 기본값 | 하는 일 | -| --- | --- | --- | -| `operation-ledger-enabled` | `false` | `true`: starter가 배포의 `GrpcOperationLedger` bean 위에 `GrpcIdempotencyInterceptor`(bean `grpcIdempotencyInterceptor`)와 `GrpcOperationLedgerRetention`(bean `grpcOperationLedgerRetention`)을 조립하고, 원장 bean이 없으면 기동을 거절한다. `false`: 두 bean 모두 없고, `IDEMPOTENCY_KEY_REQUIRED`인 메서드가 있으면 기동을 거절한다 | -| `operation-ledger-claim-ttl` | `5m` | `IN_PROGRESS` claim의 주인이 살아 있다고 믿는 시간. 지나면 같은 요청의 재시도가 claim을 넘겨받는다(`GrpcOperationLedger.reclaimStale`). 키가 필요한 모든 메서드의 deadline보다 길지 않으면 기동에서 거절한다 | -| `operation-ledger-retention` | `24h` | 끝난(`COMMITTED`/`FAILED_TERMINAL`) 레코드를 `GrpcOperationLedgerRetention.purgeExpired`가 지울 수 있게 되기 전까지 두는 시간. `IN_PROGRESS` 행은 지우지 않는다 | - -기본값: 5분 TTL은 원장 계약 시험과 interceptor 시험이 인증한 값이다. unary deadline보다 훨씬 길고, -주인이 죽은 키가 클라이언트의 재시도 인내 안에 풀릴 만큼 짧다. 24시간 보존은 HTTP 멱등성 재생 TTL -(`app.capabilities.idempotency.replay-ttl`)과 같다. 레코드를 지운 뒤 같은 키로 하는 재시도는 새 -operation이므로, 보존 시간은 호출자의 재시도 창보다 길어야 한다. - -이 키들은 `docs/registries/env-keys.yaml`에 없다. optional 빌드는 출하하는 런타임이 아니라서 -`app.grpc.platform.*` 키는 하나도 없다. 조립 루트가 플랫폼을 채택할 때 registry에 들어간다. - -**starter가 interceptor를 조립하는 이유(선택지 (b)), (a)가 아닌 이유.** 2026-11-01 성숙도 리뷰는 -(a)를 제안했다: flag를 지우고 원장 bean이 있는지로 판단한다. 2026-11-03에 (b)를 골랐고 ADR-GRPC-004에 -적었다: flag를 남기고 flag는 말 그대로의 뜻이다 — true이면 판정 함수를 조립하고 그 TTL은 설정에서 -온다. (a)는 거짓 약속을 없앴겠지만 채택하는 쪽마다 같은 조립과 TTL 검증을 손으로 다시 만들게 -했다. (b)는 그것을 한곳에 둔다. interceptor bean에는 일부러 `@ConditionalOnMissingBean`이 없다: -바꿔 넣은 bean은 `operation-ledger-claim-ttl`을 소리 없이 무시하게 된다. 돌고 있는 operation의 -중복은 기다리라고 하지 않고 거절한다(`REJECT_IN_PROGRESS`). 기다렸다가 다시 묻는 선택지는 키가 -필요한 메서드가 그것을 필요로 할 때 키가 된다. - -**서버 배선은 여전히 채택하는 쪽의 몫이고, 따로 정할 일로 남는다.** starter는 서버를 만들지 -않으므로, 판정을 조립한다고 플랫폼이 `adapter:inbound:grpc`에 배선되지는 않는다(위 "배선은 -별도 결정"을 본다). `GrpcIdempotencyInterceptor`는 판정 함수이고 `io.grpc.ServerInterceptor`가 -아니다. 채택하는 쪽은 bean을 타입으로 주입받아 자기 `IDEMPOTENCY` 단계 interceptor -(`GrpcServerInterceptorChain.builder().stage(GrpcServerInterceptorStage.IDEMPOTENCY, ...)`)나 자기 -typed service adapter에서 부른다: 변경 전에 `decide(...)`, 변경의 트랜잭션 안에서 -`recordCommit(...)`, 끝난 실패에 `recordFailure(...)`. 두 기록 호출은 모두 `PROCEED` 판정이 실어 온 -`GrpcClaimToken`을 받는다: claim을 넘겨준 시도의 커밋은 거절되고(그 트랜잭션은 롤백된다) 그 실패는 -무시된다. 그래서 느린 주인이 claim을 가져간 시도를 덮어쓰지 못한다(ADR-GRPC-004). - -**지우기 일정은 채택하는 쪽의 몫이다.** `GrpcOperationLedgerRetention.purgeExpired(now)`는 기한이 지난 -끝난 행을 한계 있는 batch(문장 하나에 500)로 지우고, batch가 덜 차서 돌아오면 멈춘다. starter는 이것을 -예약하지 않는다: scheduler를 가지지 않고 어느 replica가 돌려야 하는지 알 수 없으며, 예약된 bean은 모든 -배포에 task scheduler를 강요하게 된다. 채택하는 쪽이 자기 scheduler에서 부른다(예: 한 시간마다). -지우기가 잠긴 행을 건너뛰므로 여러 replica에서 동시에 돌려도 안전하다. 한 번도 돌리지 않아도 안전하지만 -테이블이 끝없이 커진다. - -커밋은 변경의 트랜잭션 안에서 기록해야 하고 TTL은 키가 필요한 가장 느린 메서드보다 길어야 한다. 두 -이유는 모두 ADR-GRPC-004에 있다. +@AGENTS.md diff --git a/src/platforms/messaging/AGENTS.md b/src/platforms/messaging/AGENTS.md new file mode 100644 index 00000000..9c68440a --- /dev/null +++ b/src/platforms/messaging/AGENTS.md @@ -0,0 +1,176 @@ +# messaging — 메시징 플랫폼 family의 지역 정본 + +이 문서는 messaging family의 **지역 정본(local authority)**이다. leaf 목록·gradle path·허용 의존성은 +`src/config/architecture/modules.json`이 SSOT이며 이 문서는 그것을 복제하지 않는다. 여기서 정하는 +것은 registry가 표현할 수 없는 것들이다: family별 framework 규칙, public surface 정책, Stable 승격에 +필요한 증거, runtime membership이 비어 있다는 사실의 의미. + +루트 `AGENTS.md`와 충돌하면 루트가 이긴다. + +## Family와 framework 규칙 + +leaf의 정확한 id는 registry에서 읽는다. family는 **디렉터리 이름의 접두사**가 아니라 아래 표의 +역할로 정해진다. + +| Family | 역할 | 허용 framework | +| --- | --- | --- | +| `*-api` (`core-api` — `api`·`schema` 패키지, `policy`, `reliability-api`, `transport-spi`) | 값 타입, 포트, 정책 계약 | Java stdlib만. Spring/broker SDK/logging framework 금지 | +| `schema-*` (json/avro/protobuf), `cloudevents` | 인코딩 구현 | 해당 codec 라이브러리만. Spring 금지 | +| `runtime-core`, `security`, `observability`, `admin`(계약 `admin` + 실행 `admin.runtime`), `reliability` | framework-free 실행 로직 | Micrometer는 `observability`에서만. 나머지는 stdlib | +| `kafka` | broker adapter | 해당 broker client. Spring은 client가 곧 Spring인 경우만 | +| `reliability-jdbc-postgresql` | 관계형 신뢰성 adapter (outbox·inbox repository, admin journal) | Spring JDBC / Spring TX. **JPA 아님** — 이름이 곧 계약이다 | +| `spring-boot-starter`, `spring-boot-starter-kafka` | 조립 경계 | Spring Boot autoconfigure. 여기서만 | +| `testkit` | 테스트 지원 | Testcontainers, JUnit. production leaf가 의존하지 않는다 | + +신뢰성 기능은 세 leaf다. `messaging-reliability-api`가 vendor 중립 port(`OutboxRepository`, +`InboxRepository`)를, `messaging-reliability`가 그 port만 보는 relay·consumer 로직(stdlib)을, +`messaging-reliability-jdbc-postgresql`이 port의 관계형 구현과 migration(`V1001..V1005`, `V1101`)을 +갖는다. 예전에는 `outbox-jdbc-postgresql` 하나가 relay 로직과 PG repository와 admin journal을 함께 +가졌고 inbox도 같은 모양이었다(2026-09-25 리뷰 후속 작업에서 나눴다). 구현 leaf가 `jdbc-postgresql`로 명명된 이유: 구현은 Spring +JDBC이고 SQL은 `jsonb` · `FOR UPDATE SKIP LOCKED` · `ON CONFLICT` · `TIMESTAMPTZ`로 PostgreSQL +전용이다. `jpa`라는 이름은 사용하지 않는 기술을 광고하고, vendor 중립 port가 어디 있는지도 숨겼다. + +### 공용 다이제스트 헬퍼를 복사해 두는 이유 + +`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 비교 등)는 +`shared-contract`의 정본과 같은 규칙인지 함께 본다. + +### 인증·인가 거부의 발행 재시도 여부 (Publish retryability of authentication and authorization) + +이 제품 안에는 같은 category에 대한 재시도 규칙이 둘 있다. 의도다. + +- category 기본값: `FailureDescriptor.defaultRetryable(AUTHENTICATION | AUTHORIZATION) = false`. 소비 쪽 + 재시도 엔진(`DefaultRetryDecisionEngine`)은 policy가 category를 따로 정하지 않으면 이 기본값과 + descriptor의 `retryable`을 둘 다 요구한다. 그래서 인가받지 못한 메시지의 재전달은 지금도 재시도하지 않는다. +- publish 거부의 `retryable`: `KafkaPublishFailureClassifier`는 인증·인가 거부에 `retryable = true`를 붙인다. + broker가 레코드를 저장하지 않았고, credential 교체나 application보다 늦게 배포된 ACL은 몇 분 동안 모든 + publish를 거부한 뒤 멈추기 때문이다. `retryable`을 믿는 publisher가 그 몇 분 동안의 레코드를 영구 보류하지 + 않게 하려는 것이다. + +다시 시도하면 될 거부를 relay가 즉시 DEAD로 보내던 결함의 수정(2026-11-01 성숙도 리뷰 뒤)이 이 제품에서 바꾼 것(모두 +publish 경로, 소비 경로 동작은 그대로): + +- `KafkaPublishFailureClassifier`: 인증·인가 거부를 `retryable = true`로. +- `DefaultMessagePublisher`: runtime이 없을 때의 거부(`PUBLISH_RUNTIME_UNAVAILABLE`)를 `retryable = true`로. +- `KafkaMessagingTransport`: 닫힌 transport의 거부(`KAFKA_TRANSPORT_CLOSED`)를 `retryable = true`로. +- `MessagingShutdownLifecycle.PHASE`: platform 밖 relay의 순서 테스트가 참조하도록 public. + +버린 대안: vendored 제품은 그대로 두고 application bridge(ACL)가 category를 보고 "인증·인가면 재시도"로 +번역하는 것. 버린 이유: `retryable`은 이 제품이 "같은 레코드를 나중에 다시 보내면 받아질 수 있나"를 말하는 +자리다. bridge가 category로 그 판단을 다시 하면 같은 사실을 제품과 bridge가 따로 정하고, 이 제품의 +`PublishResult`를 읽는 다른 호출자는 bridge와 다른 답을 본다. 대신 이 제품 주석은 소비자 이름(application +relay, `composition:outbox-relay`)을 부르지 않는다 — "flag를 믿는 publisher"로 쓴다(2026-11-03). + +## Public surface 정책 + +- **vendor 타입을 public signature에 노출하면 그 의존성은 `api`로 선언한다.** 숨긴다고 타입이 + 숨겨지지 않는다 — consumer가 이 모듈이 문서화한 API에 대해 컴파일하지 못하게 만들 뿐이다. + (`kafka-clients`, `cloudevents-api`, `micrometer-core`, `avro`, + `protobuf-java`가 이 규칙으로 `api`다.) +- 반대로 **노출하지 않는 것은 `implementation`으로 낮춘다.** starter가 노출하지 않는 하위 모듈을 + `implementation`으로 내린 것이, JSON codec이 `ObjectMapper`를 private으로만 쓰고 Jackson을 + `implementation`으로 둔 것이 그 예다. +- 이 규칙은 문서가 아니라 `MessagingPublicSurfaceContractTest`가 붙들고 있다. leaf의 production + source에서 public/protected 시그니처에 등장하는 vendor 라이브러리를 뽑아 그 leaf의 + `build.gradle`이 `api`로 선언했는지 대조하고, starter의 `api` closure에 broker client 두 개가 + 들어오지 않는 것도 함께 본다. Spring Framework/Boot는 대상이 아니다 — 조립 경계 안에서만 + 등장하고 adopter가 이름 부를 일이 없다. +- 새 public 타입은 그 모듈의 계약이다. 삭제·시그니처 변경은 breaking change로 취급한다. + +## Application runtime에 포함되는 기준 + +기본 조립에는 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 목록을 복제하지 않는다. +모듈이 있으면 켜지고(`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` 제거 표). +새 leaf를 application에 채택할 때는 starter 또는 composition dependency와 architecture edge policy, +qualification/support 상태를 함께 변경한다. + +## application이 이 family에 도달하는 경로 (cutover 완료) + +리뷰(`docs/reviews/2026-08-14-messaging-module-code-review.md` §6.1·§6.3)가 정한 +`application-owned port → platform anti-corruption bridge → platform` 경로는 이제 존재한다. + +- application-owned port: `IntegrationEventPublishPort` +- bridge: `adapter/outbound/messaging/platformbridge/PlatformIntegrationEventPublishAdapter` +- platform boundary: `EncodedMessagePublisher` +- central implementation: `DefaultMessagePublisher` + +bridge는 exact canonical envelope bytes를 다시 serialize하지 않고, destination/access/admission/runtime +lease/transport/outcome normalization/observation은 platform 중앙 publish path를 그대로 탄다. bridge +package는 `messaging-core-api`만 보며 concrete runtime/transport/Kafka 타입을 +직접 보지 않는다. + +**application bridge cutover는 2026-09-28에 끝났다(2026-09-25 소유자 결정).** application의 outbox append는 canonical +`OutboxAppendPort` 하나이고, relay는 claim한 row의 validated event를 이 bridge로만 보낸다. legacy +`OutboxEvent`·`LegacyOutboxAppendPort`와 `MessageBroker → KafkaSender` R0 경로(TLS/SASL을 적용하지 +않던 두 번째 producer)는 삭제했다. 남은 Kafka producer는 platform의 것 하나이고, broker security +profile(`KafkaSecurityConfigurer`)을 적용한다. + +canonical bridge의 producer identity는 `app.messaging.producer-id`로 명시한다. 값이 없으면 bridge bean을 +만들지 않으며 `spring.application.name`/host/pod 이름에서 identity를 발명하지 않는다. bridge가 없으면 +relay가 발행할 곳이 없으므로 messaging 모듈이 켜진 상태에서는 기동이 거부된다. + +`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 파일과 +다르면 기동이 실패한다. payload를 JSON Schema로 매번 검증하려는 서비스는 자기 encoder bean을 두면 된다. + +## Stable 승격에 필요한 증거 + +adapter를 Experimental → Stable로 올릴 때 필요한 것 (`docs/messaging/support-matrix.md`가 현재 +상태를 기록한다): + +1. 실제 broker container를 쓰는 fault 시나리오 lane이 존재하고, 그 lane이 + `BrokerCertificationEvidence`를 산출한다. +2. `NetworkFaultScenario` 전 항목에 대해 evidence가 있거나, 없는 항목이 `knownGaps`로 명시된다. +3. capability 선언이 코드에서 파생된다 — `MessagingCapabilities`에 손으로 `true`를 쓰는 것은 + 증거가 아니다. +4. publish 실패 분류가 typed signal에서만 나온다. exception class 이름 substring 판정은 + Experimental에서도 금지다. +5. unknown failure의 기본값이 `AMBIGUOUS`다. `REJECTED`는 전송이 시작되지 않았다는 typed 증거가 + 있을 때만. + +Stable 문구는 evidence manifest가 존재할 때만 문서에 쓴다. + +증거를 만드는 것은 인증 레인이고, manifest는 그 실행의 출력이다: + +```bash +./gradlew :messaging:messaging-kafka:verifyMessagingCertificationEvidence --console=plain +``` + +레인(`messagingCertificationTest`)은 Toxiproxy를 broker 앞에 두고 장애를 주입하며, +통과한 시나리오마다 `BrokerCertificationEvidence` 한 줄을 +`messaging-testkit/src/main/resources/messaging/broker-certification-evidence.jsonl`에 쓴다. +게이트는 커밋된 manifest와 이번 실행의 출력을 대조한다 — **manifest를 손으로 고치면 실패하고, +레인을 돌리면 manifest가 다시 쓰인다.** 이 레인만은 Docker 가드를 달지 않는다(없으면 실패한다). +skip하는 인증 레인은 아무도 켜지 않은 브로커에 대해 성공을 보고하기 때문이며, 그래서 `test`에서는 +`messaging-certification` 태그로 제외된다. + +## Focused test + +leaf의 `gradle_path`를 registry에서 읽어 파생한다. + +```bash +cd src +./gradlew :test --console=plain +``` + +Family 전체 검증: + +```bash +./gradlew verifyCleanArchitectureDependencies --console=plain +./gradlew architectureCheck --console=plain +./gradlew verifyDependencyLocks --console=plain +``` diff --git a/src/platforms/messaging/CLAUDE.md b/src/platforms/messaging/CLAUDE.md index 807a5890..43c994c2 100644 --- a/src/platforms/messaging/CLAUDE.md +++ b/src/platforms/messaging/CLAUDE.md @@ -1,176 +1 @@ -# messaging — 메시징 플랫폼 family의 지역 정본 - -이 문서는 messaging family의 **지역 정본(local authority)**이다. leaf 목록·gradle path·허용 의존성은 -`src/config/architecture/modules.json`이 SSOT이며 이 문서는 그것을 복제하지 않는다. 여기서 정하는 -것은 registry가 표현할 수 없는 것들이다: family별 framework 규칙, public surface 정책, Stable 승격에 -필요한 증거, runtime membership이 비어 있다는 사실의 의미. - -Root 정책(`CLAUDE.md` / `AGENTS.md`)과 충돌하면 root가 이긴다. - -## Family와 framework 규칙 - -leaf의 정확한 id는 registry에서 읽는다. family는 **디렉터리 이름의 접두사**가 아니라 아래 표의 -역할로 정해진다. - -| Family | 역할 | 허용 framework | -| --- | --- | --- | -| `*-api` (`core-api` — `api`·`schema` 패키지, `policy`, `reliability-api`, `transport-spi`) | 값 타입, 포트, 정책 계약 | Java stdlib만. Spring/broker SDK/logging framework 금지 | -| `schema-*` (json/avro/protobuf), `cloudevents` | 인코딩 구현 | 해당 codec 라이브러리만. Spring 금지 | -| `runtime-core`, `security`, `observability`, `admin`(계약 `admin` + 실행 `admin.runtime`), `reliability` | framework-free 실행 로직 | Micrometer는 `observability`에서만. 나머지는 stdlib | -| `kafka` | broker adapter | 해당 broker client. Spring은 client가 곧 Spring인 경우만 | -| `reliability-jdbc-postgresql` | 관계형 신뢰성 adapter (outbox·inbox repository, admin journal) | Spring JDBC / Spring TX. **JPA 아님** — 이름이 곧 계약이다 | -| `spring-boot-starter`, `spring-boot-starter-kafka` | 조립 경계 | Spring Boot autoconfigure. 여기서만 | -| `testkit` | 테스트 지원 | Testcontainers, JUnit. production leaf가 의존하지 않는다 | - -신뢰성 기능은 세 leaf다. `messaging-reliability-api`가 vendor 중립 port(`OutboxRepository`, -`InboxRepository`)를, `messaging-reliability`가 그 port만 보는 relay·consumer 로직(stdlib)을, -`messaging-reliability-jdbc-postgresql`이 port의 관계형 구현과 migration(`V1001..V1005`, `V1101`)을 -갖는다. 예전에는 `outbox-jdbc-postgresql` 하나가 relay 로직과 PG repository와 admin journal을 함께 -가졌고 inbox도 같은 모양이었다(2026-09-25 리뷰 후속 작업에서 나눴다). 구현 leaf가 `jdbc-postgresql`로 명명된 이유: 구현은 Spring -JDBC이고 SQL은 `jsonb` · `FOR UPDATE SKIP LOCKED` · `ON CONFLICT` · `TIMESTAMPTZ`로 PostgreSQL -전용이다. `jpa`라는 이름은 사용하지 않는 기술을 광고하고, vendor 중립 port가 어디 있는지도 숨겼다. - -### 공용 다이제스트 헬퍼를 복사해 두는 이유 - -`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 비교 등)는 -`shared-contract`의 정본과 같은 규칙인지 함께 본다. - -### 인증·인가 거부의 발행 재시도 여부 (Publish retryability of authentication and authorization) - -이 제품 안에는 같은 category에 대한 재시도 규칙이 둘 있다. 의도다. - -- category 기본값: `FailureDescriptor.defaultRetryable(AUTHENTICATION | AUTHORIZATION) = false`. 소비 쪽 - 재시도 엔진(`DefaultRetryDecisionEngine`)은 policy가 category를 따로 정하지 않으면 이 기본값과 - descriptor의 `retryable`을 둘 다 요구한다. 그래서 인가받지 못한 메시지의 재전달은 지금도 재시도하지 않는다. -- publish 거부의 `retryable`: `KafkaPublishFailureClassifier`는 인증·인가 거부에 `retryable = true`를 붙인다. - broker가 레코드를 저장하지 않았고, credential 교체나 application보다 늦게 배포된 ACL은 몇 분 동안 모든 - publish를 거부한 뒤 멈추기 때문이다. `retryable`을 믿는 publisher가 그 몇 분 동안의 레코드를 영구 보류하지 - 않게 하려는 것이다. - -다시 시도하면 될 거부를 relay가 즉시 DEAD로 보내던 결함의 수정(2026-11-01 성숙도 리뷰 뒤)이 이 제품에서 바꾼 것(모두 -publish 경로, 소비 경로 동작은 그대로): - -- `KafkaPublishFailureClassifier`: 인증·인가 거부를 `retryable = true`로. -- `DefaultMessagePublisher`: runtime이 없을 때의 거부(`PUBLISH_RUNTIME_UNAVAILABLE`)를 `retryable = true`로. -- `KafkaMessagingTransport`: 닫힌 transport의 거부(`KAFKA_TRANSPORT_CLOSED`)를 `retryable = true`로. -- `MessagingShutdownLifecycle.PHASE`: platform 밖 relay의 순서 테스트가 참조하도록 public. - -버린 대안: vendored 제품은 그대로 두고 application bridge(ACL)가 category를 보고 "인증·인가면 재시도"로 -번역하는 것. 버린 이유: `retryable`은 이 제품이 "같은 레코드를 나중에 다시 보내면 받아질 수 있나"를 말하는 -자리다. bridge가 category로 그 판단을 다시 하면 같은 사실을 제품과 bridge가 따로 정하고, 이 제품의 -`PublishResult`를 읽는 다른 호출자는 bridge와 다른 답을 본다. 대신 이 제품 주석은 소비자 이름(application -relay, `composition:outbox-relay`)을 부르지 않는다 — "flag를 믿는 publisher"로 쓴다(2026-11-03). - -## Public surface 정책 - -- **vendor 타입을 public signature에 노출하면 그 의존성은 `api`로 선언한다.** 숨긴다고 타입이 - 숨겨지지 않는다 — consumer가 이 모듈이 문서화한 API에 대해 컴파일하지 못하게 만들 뿐이다. - (`kafka-clients`, `cloudevents-api`, `micrometer-core`, `avro`, - `protobuf-java`가 이 규칙으로 `api`다.) -- 반대로 **노출하지 않는 것은 `implementation`으로 낮춘다.** starter가 노출하지 않는 하위 모듈을 - `implementation`으로 내린 것이, JSON codec이 `ObjectMapper`를 private으로만 쓰고 Jackson을 - `implementation`으로 둔 것이 그 예다. -- 이 규칙은 문서가 아니라 `MessagingPublicSurfaceContractTest`가 붙들고 있다. leaf의 production - source에서 public/protected 시그니처에 등장하는 vendor 라이브러리를 뽑아 그 leaf의 - `build.gradle`이 `api`로 선언했는지 대조하고, starter의 `api` closure에 broker client 두 개가 - 들어오지 않는 것도 함께 본다. Spring Framework/Boot는 대상이 아니다 — 조립 경계 안에서만 - 등장하고 adopter가 이름 부를 일이 없다. -- 새 public 타입은 그 모듈의 계약이다. 삭제·시그니처 변경은 breaking change로 취급한다. - -## Application runtime에 포함되는 기준 - -기본 조립에는 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 목록을 복제하지 않는다. -모듈이 있으면 켜지고(`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` 제거 표). -새 leaf를 application에 채택할 때는 starter 또는 composition dependency와 architecture edge policy, -qualification/support 상태를 함께 변경한다. - -## application이 이 family에 도달하는 경로 (cutover 완료) - -리뷰(`docs/reviews/2026-08-14-messaging-module-code-review.md` §6.1·§6.3)가 정한 -`application-owned port → platform anti-corruption bridge → platform` 경로는 이제 존재한다. - -- application-owned port: `IntegrationEventPublishPort` -- bridge: `adapter/outbound/messaging/platformbridge/PlatformIntegrationEventPublishAdapter` -- platform boundary: `EncodedMessagePublisher` -- central implementation: `DefaultMessagePublisher` - -bridge는 exact canonical envelope bytes를 다시 serialize하지 않고, destination/access/admission/runtime -lease/transport/outcome normalization/observation은 platform 중앙 publish path를 그대로 탄다. bridge -package는 `messaging-core-api`만 보며 concrete runtime/transport/Kafka 타입을 -직접 보지 않는다. - -**application bridge cutover는 2026-09-28에 끝났다(2026-09-25 소유자 결정).** application의 outbox append는 canonical -`OutboxAppendPort` 하나이고, relay는 claim한 row의 validated event를 이 bridge로만 보낸다. legacy -`OutboxEvent`·`LegacyOutboxAppendPort`와 `MessageBroker → KafkaSender` R0 경로(TLS/SASL을 적용하지 -않던 두 번째 producer)는 삭제했다. 남은 Kafka producer는 platform의 것 하나이고, broker security -profile(`KafkaSecurityConfigurer`)을 적용한다. - -canonical bridge의 producer identity는 `app.messaging.producer-id`로 명시한다. 값이 없으면 bridge bean을 -만들지 않으며 `spring.application.name`/host/pod 이름에서 identity를 발명하지 않는다. bridge가 없으면 -relay가 발행할 곳이 없으므로 messaging 모듈이 켜진 상태에서는 기동이 거부된다. - -`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 파일과 -다르면 기동이 실패한다. payload를 JSON Schema로 매번 검증하려는 서비스는 자기 encoder bean을 두면 된다. - -## Stable 승격에 필요한 증거 - -adapter를 Experimental → Stable로 올릴 때 필요한 것 (`docs/messaging/support-matrix.md`가 현재 -상태를 기록한다): - -1. 실제 broker container를 쓰는 fault 시나리오 lane이 존재하고, 그 lane이 - `BrokerCertificationEvidence`를 산출한다. -2. `NetworkFaultScenario` 전 항목에 대해 evidence가 있거나, 없는 항목이 `knownGaps`로 명시된다. -3. capability 선언이 코드에서 파생된다 — `MessagingCapabilities`에 손으로 `true`를 쓰는 것은 - 증거가 아니다. -4. publish 실패 분류가 typed signal에서만 나온다. exception class 이름 substring 판정은 - Experimental에서도 금지다. -5. unknown failure의 기본값이 `AMBIGUOUS`다. `REJECTED`는 전송이 시작되지 않았다는 typed 증거가 - 있을 때만. - -Stable 문구는 evidence manifest가 존재할 때만 문서에 쓴다. - -증거를 만드는 것은 인증 레인이고, manifest는 그 실행의 출력이다: - -```bash -./gradlew :messaging:messaging-kafka:verifyMessagingCertificationEvidence --console=plain -``` - -레인(`messagingCertificationTest`)은 Toxiproxy를 broker 앞에 두고 장애를 주입하며, -통과한 시나리오마다 `BrokerCertificationEvidence` 한 줄을 -`messaging-testkit/src/main/resources/messaging/broker-certification-evidence.jsonl`에 쓴다. -게이트는 커밋된 manifest와 이번 실행의 출력을 대조한다 — **manifest를 손으로 고치면 실패하고, -레인을 돌리면 manifest가 다시 쓰인다.** 이 레인만은 Docker 가드를 달지 않는다(없으면 실패한다). -skip하는 인증 레인은 아무도 켜지 않은 브로커에 대해 성공을 보고하기 때문이며, 그래서 `test`에서는 -`messaging-certification` 태그로 제외된다. - -## Focused test - -leaf의 `gradle_path`를 registry에서 읽어 파생한다. - -```bash -cd src -./gradlew :test --console=plain -``` - -Family 전체 검증: - -```bash -./gradlew verifyCleanArchitectureDependencies --console=plain -./gradlew architectureCheck --console=plain -./gradlew verifyDependencyLocks --console=plain -``` +@AGENTS.md diff --git a/src/shared-contract/AGENTS.md b/src/shared-contract/AGENTS.md new file mode 100644 index 00000000..51539ac8 --- /dev/null +++ b/src/shared-contract/AGENTS.md @@ -0,0 +1,69 @@ +# shared-contract — 골격 전체가 쓰는 운영 계약 + +## 등록 정보 + +- 모듈 ID: `shared-contract` +- Gradle 경로: `:shared-contract` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :shared-contract:test --console=plain` +- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. +- registry 정본: `src/config/architecture/modules.json`. + +패키지 루트: `dev.caskeleton.shared`. + +예전에 코드 주석에 두던 설계 결정(오류 코드 분류, 응답 envelope 모양, metric cardinality 한계, +tracing 이음매, domain-context 전파)은 [README.md](README.md)에 있다. 이 파일은 모듈 규칙의 정본으로 +남는다. + +## 책임 (Responsibility) +- 응답 envelope(`response/Envelope`, `response/ApiError`, `response/BulkEnvelope`, `response/BulkItemResult`). +- 오류 코드 계약(`error/ApiErrorCode` 인터페이스, `error/OperationalError` enum, + `error/ApiErrorCarrier`)과 클라이언트에 보여 줄 문구 표 하나(`error/ClientErrorMessages`. + 한국어이고 `Category`마다 문구 하나이며 모든 전송 계층이 쓴다). +- 계층을 가로지르는 mapper 표지 예외(`error/MappingException`). +- 요청 값 계약(`request/Patch`). +- tracing 계약 타입(`tracing/TraceParent`, `tracing/SpanErrorRecorder`) — W3C `traceparent` 값 타입과 + span 오류 기록 이음매(feature-distributed-tracing-contract. OTel tracer 런타임은 fork가 켜는 + 이음매라서 이 타입들은 Java 표준 라이브러리만 쓴다). +- 모든 leaf가 복사해 쓰던 표준 라이브러리 도우미(2026-09-25 리뷰 후속으로 여기로 옮겼다): + `digest/Sha256`(SHA-256 digest 값과 유일한 `MessageDigest.getInstance("SHA-256")`), + `digest/HmacSha256`(서명과 상수 시간 검증), `retry/Backoff`(상한 있는 지수 ceiling. "full jitter"는 + `U[0, ceiling]`이고 다른 뜻이 아니다). 들여온 `messaging:*`와 optional gRPC 빌드는 이 모듈에 + 의존하지 않고 자기 사본을 둔다. 각 제품의 AGENTS.md가 이유를 적는다(다른 제품이다. 2026-08-14 메시징 + 모듈 리뷰 뒤에 정했다). 이 도우미가 필요한 템플릿 leaf는 모두 `shared-contract` edge를 두고 복사하지 + 않고 쓴다. identifier, persistence-mongo, application-objectstorage, redis-sdk가 바로 이 때문에 + edge를 받았고(2026-11-03에 정함), 각각 JVM 밖에서 계산한 벡터로 출력을 고정하는 시험이 있다. +- `observability/MdcKeys`: 모든 전송 계층(web, GraphQL, STOMP, gRPC)이 요청의 correlation을 넣는 + snake_case MDC 키 이름(registry `docs/registries/mdc-keys.yaml`). +- `ratelimit/`: web edge와 Redis 어댑터 사이에 있는 provider 중립 edge rate-limit 포트 + (`EdgeRateLimitPort`)와 그 값 타입(README 「ratelimit」). +- `security/Permission`: `AuthorizationPort`에 묻는 `resource:action` 권한 값(README 「security」). +- `concurrency/`: domain-context 전파 포트와 그 `ThreadLocal` 기본 구현(README 「concurrency」). +- `runtime/RuntimeEnvironment`: 모든 leaf가 「운영 환경인가?」에 답할 때 쓰는 유일한 runtime profile + 어휘. +- `metrics/ForbiddenMetricTags`: 어떤 metric도 실으면 안 되는 high-cardinality tag 키. +- 이 모듈의 패키지는 위가 전부이고 다른 패키지는 둘 수 없다: + `ForbiddenApiArchitectureTest.SHARED_CONTRACT_CONTAINS_ONLY_OPERATIONAL_CONTRACT_PACKAGES`가 + `dev.caskeleton.shared` 아래 다른 패키지에 있는 클래스와 루트에 바로 있는 클래스를 거절한다. 루트에는 + `package-info`만 있다. 새 계약 패키지는 그 시험의 `SHARED_CONTRACT_PACKAGES`와 이 목록에 함께 + 넣는다. `SharedContractPackageRuleTest`는 `SHARED_CONTRACT_PACKAGES`와 모듈의 패키지가 다르면 + 실패한다. +- 계약 시험만 읽는 registry 규칙 사본은 `main`이 아니라 `testFixtures`에 둔다: + `metrics/MetricNaming`, `metrics/CardinalityBounds`, `metrics/AlertSeverity`, + `tracing/BaggageAllowlist`. 운영 코드가 쓰게 될 때만 `main`으로 옮긴다. +- `contracts/messaging/envelope/` 아래의 범용 메시징 envelope schema 리소스. 전송 중립 envelope + metadata만 가진다. 기능 payload schema는 그 기능을 가진 모듈에 남는다. 리소스가 있다고 런타임에 + 찾아지거나 등록되는 것은 아니다. + +## 허용 +- Java 표준 라이브러리**만**. Spring, Jackson, JPA import는 없다. + +## 금지 (Forbidden) +- 업무·도메인 개념(도메인 오류 코드는 그것을 쓰는 모듈에 둔다). +- 프레임워크 import(HTTP 상태는 전송 중립 `int`로 나타내고 web 모듈이 대응시킨다). +- 메시징 어댑터의 Task 6 validator 검증이 생기기 전에 Draft 2020-12 validator 호환을 주장하기. + +## 테스트 +```bash +cd src +./gradlew :shared-contract:test +``` diff --git a/src/shared-contract/CLAUDE.md b/src/shared-contract/CLAUDE.md index 6722710c..43c994c2 100644 --- a/src/shared-contract/CLAUDE.md +++ b/src/shared-contract/CLAUDE.md @@ -1,69 +1 @@ -# shared-contract — 골격 전체가 쓰는 운영 계약 - -## 등록 정보 - -- 모듈 ID: `shared-contract` -- Gradle 경로: `:shared-contract` -- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :shared-contract:test --console=plain` -- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. -- registry 정본: `src/config/architecture/modules.json`. - -패키지 루트: `dev.caskeleton.shared`. - -예전에 코드 주석에 두던 설계 결정(오류 코드 분류, 응답 envelope 모양, metric cardinality 한계, -tracing 이음매, domain-context 전파)은 [README.md](README.md)에 있다. 이 파일은 모듈 규칙의 정본으로 -남는다. - -## 책임 (Responsibility) -- 응답 envelope(`response/Envelope`, `response/ApiError`, `response/BulkEnvelope`, `response/BulkItemResult`). -- 오류 코드 계약(`error/ApiErrorCode` 인터페이스, `error/OperationalError` enum, - `error/ApiErrorCarrier`)과 클라이언트에 보여 줄 문구 표 하나(`error/ClientErrorMessages`. - 한국어이고 `Category`마다 문구 하나이며 모든 전송 계층이 쓴다). -- 계층을 가로지르는 mapper 표지 예외(`error/MappingException`). -- 요청 값 계약(`request/Patch`). -- tracing 계약 타입(`tracing/TraceParent`, `tracing/SpanErrorRecorder`) — W3C `traceparent` 값 타입과 - span 오류 기록 이음매(feature-distributed-tracing-contract. OTel tracer 런타임은 fork가 켜는 - 이음매라서 이 타입들은 Java 표준 라이브러리만 쓴다). -- 모든 leaf가 복사해 쓰던 표준 라이브러리 도우미(2026-09-25 리뷰 후속으로 여기로 옮겼다): - `digest/Sha256`(SHA-256 digest 값과 유일한 `MessageDigest.getInstance("SHA-256")`), - `digest/HmacSha256`(서명과 상수 시간 검증), `retry/Backoff`(상한 있는 지수 ceiling. "full jitter"는 - `U[0, ceiling]`이고 다른 뜻이 아니다). 들여온 `messaging:*`와 optional gRPC 빌드는 이 모듈에 - 의존하지 않고 자기 사본을 둔다. 각 제품의 CLAUDE.md가 이유를 적는다(다른 제품이다. 2026-08-14 메시징 - 모듈 리뷰 뒤에 정했다). 이 도우미가 필요한 템플릿 leaf는 모두 `shared-contract` edge를 두고 복사하지 - 않고 쓴다. identifier, persistence-mongo, application-objectstorage, redis-sdk가 바로 이 때문에 - edge를 받았고(2026-11-03에 정함), 각각 JVM 밖에서 계산한 벡터로 출력을 고정하는 시험이 있다. -- `observability/MdcKeys`: 모든 전송 계층(web, GraphQL, STOMP, gRPC)이 요청의 correlation을 넣는 - snake_case MDC 키 이름(registry `docs/registries/mdc-keys.yaml`). -- `ratelimit/`: web edge와 Redis 어댑터 사이에 있는 provider 중립 edge rate-limit 포트 - (`EdgeRateLimitPort`)와 그 값 타입(README 「ratelimit」). -- `security/Permission`: `AuthorizationPort`에 묻는 `resource:action` 권한 값(README 「security」). -- `concurrency/`: domain-context 전파 포트와 그 `ThreadLocal` 기본 구현(README 「concurrency」). -- `runtime/RuntimeEnvironment`: 모든 leaf가 「운영 환경인가?」에 답할 때 쓰는 유일한 runtime profile - 어휘. -- `metrics/ForbiddenMetricTags`: 어떤 metric도 실으면 안 되는 high-cardinality tag 키. -- 이 모듈의 패키지는 위가 전부이고 다른 패키지는 둘 수 없다: - `ForbiddenApiArchitectureTest.SHARED_CONTRACT_CONTAINS_ONLY_OPERATIONAL_CONTRACT_PACKAGES`가 - `dev.caskeleton.shared` 아래 다른 패키지에 있는 클래스와 루트에 바로 있는 클래스를 거절한다. 루트에는 - `package-info`만 있다. 새 계약 패키지는 그 시험의 `SHARED_CONTRACT_PACKAGES`와 이 목록에 함께 - 넣는다. `SharedContractPackageRuleTest`는 `SHARED_CONTRACT_PACKAGES`와 모듈의 패키지가 다르면 - 실패한다. -- 계약 시험만 읽는 registry 규칙 사본은 `main`이 아니라 `testFixtures`에 둔다: - `metrics/MetricNaming`, `metrics/CardinalityBounds`, `metrics/AlertSeverity`, - `tracing/BaggageAllowlist`. 운영 코드가 쓰게 될 때만 `main`으로 옮긴다. -- `contracts/messaging/envelope/` 아래의 범용 메시징 envelope schema 리소스. 전송 중립 envelope - metadata만 가진다. 기능 payload schema는 그 기능을 가진 모듈에 남는다. 리소스가 있다고 런타임에 - 찾아지거나 등록되는 것은 아니다. - -## 허용 -- Java 표준 라이브러리**만**. Spring, Jackson, JPA import는 없다. - -## 금지 (Forbidden) -- 업무·도메인 개념(도메인 오류 코드는 그것을 쓰는 모듈에 둔다). -- 프레임워크 import(HTTP 상태는 전송 중립 `int`로 나타내고 web 모듈이 대응시킨다). -- 메시징 어댑터의 Task 6 validator 검증이 생기기 전에 Draft 2020-12 validator 호환을 주장하기. - -## 테스트 -```bash -cd src -./gradlew :shared-contract:test -``` +@AGENTS.md diff --git a/src/shared-contract/README.md b/src/shared-contract/README.md index b22731a4..998e49ac 100644 --- a/src/shared-contract/README.md +++ b/src/shared-contract/README.md @@ -3,7 +3,7 @@ 스켈레톤 전역 운영 계약(operational contract) 모듈. 패키지 루트: `dev.caskeleton.shared`. 모듈 책임·허용/금지 의존(Java 표준 라이브러리 only)·테스트 명령 같은 **모듈 규칙**은 -[CLAUDE.md](CLAUDE.md) 가 SSOT 다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를 +[AGENTS.md](AGENTS.md) 가 SSOT 다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를 모아둔 참조용 기록이다 — 코드를 읽다 "왜 이렇게 했나"가 궁금할 때 본다. 아래 설명은 별도 추적 ID를 몰라도 읽히도록 결정의 배경과 트레이드오프를 문장으로 풀어 둔다.