Merge pull request 'docs!: 번역 네 묶음을 합치고 문서 검사 장치를 마무리한다' (#3) from claude/i2-docs-merge-02df15 into main

This commit was merged in pull request #3.
This commit is contained in:
2026-11-07 11:45:21 +00:00
236 changed files with 10396 additions and 11329 deletions
+67 -67
View File
@@ -1,92 +1,92 @@
# Dependency Vulnerability Policy # 의존성 취약점 정책
This policy is enforced by 이 정책을 강제하는 것은
[`dependency-vulnerability.yml`](workflows/dependency-vulnerability.yml), [`dependency-vulnerability.yml`](workflows/dependency-vulnerability.yml),
[`dependency-review-config.yml`](dependency-review-config.yml), [`dependency-review-config.yml`](dependency-review-config.yml),
[`../.trivyignore.yaml`](../.trivyignore.yaml), CODEOWNERS, and [`../.trivyignore.yaml`](../.trivyignore.yaml), CODEOWNERS,
[`../renovate.json`](../renovate.json). [`../renovate.json`](../renovate.json)이다.
## Execution and platform boundary ## 실행 위치와 플랫폼 경계
Canonical workflow files live under `.github/workflows`. The current origin is Gitea and 정본 workflow 파일은 `.github/workflows` 아래에 있다. 지금 origin은 Gitea이고, 서버 쪽 Actions는 밖에서
server-side Actions is externally disabled; committing these controls does not enable or prove 꺼져 있다. 이 통제를 커밋해도 원격 실행이 켜지거나 증명되지 않는다. 관리자가 따로 Actions를 켜고, 맞는
remote execution. An administrator must enable Actions, provide compatible runners, configure runner를 주고, 필수 검사(required check)를 설정하고, code owner 리뷰를 필수로 해야 한다.
required checks, and require code-owner review separately.
External actions execute only by verified full commit SHA; inline comments retain the immutable 외부 action은 확인한 전체 커밋 SHA로만 실행한다. 리뷰를 위해 같은 줄 주석에 바뀌지 않는 릴리스 태그를
release tag for review. GitHub dependency review publishes check output but never writes a PR 남긴다. GitHub dependency review는 검사 결과만 내고 PR 요약 댓글은 쓰지 않는다. 그래서 workflow 전체의
summary comment, preserving the workflow-wide `contents: read` permission. `contents: read` 권한이 유지된다.
GitHub dependency review and dependency submission depend on GitHub.com APIs. They are guarded by GitHub dependency review와 dependency submission은 GitHub.com API에 기댄다. 둘은
`github.server_url == 'https://github.com'` and intentionally skip on Gitea. `trivy-fs` is the `github.server_url == 'https://github.com'` 조건으로 막혀 있고, Gitea에서는 일부러 건너뛴다. `trivy-fs`는
platform-neutral release-blocking snapshot and runs for pull requests, `main` pushes, daily 플랫폼에 묶이지 않는, 릴리스를 막는 전체 스냅숏 검사다. pull request, `main` push, 매일 예약 실행, 손으로
schedule, and manual dispatch. 부른 실행에서 돈다.
The later supply-chain slice owns image builds/scans, SBOM, signing, provenance, tag release, and 이미지 빌드·스캔, SBOM, 서명, provenance, 태그 릴리스는 `workflows/release.yml`이 맡는다. 이 정책은 그
retention. This policy does not claim those absent jobs. job을 다루지 않는다.
## Severity and response ## 심각도와 대응
| Severity | CI posture | Target remediation | | 심각도 | CI 처리 | 고칠 기한 |
| --- | --- | --- | | --- | --- | --- |
| KEV / Critical | block | 7 days or the CISA due date, whichever is sooner | | KEV / Critical | 막는다 | 7일 또는 CISA 기한 중 빠른 쪽 |
| High | block | 30 days | | High | 막는다 | 30일 |
| Medium | advisory | 90 days | | Medium | 알리기만 한다 | 90일 |
| Low | advisory | best effort | | Low | 알리기만 한다 | 가능한 대로 |
High/Critical is the template's release threshold. The exact threshold and remediation targets are High/Critical이 이 템플릿의 릴리스 기준이다. 정확한 기준과 고칠 기한은 외부 규정이 아니라 팀 정책이다.
team policy rather than an external mandate and should be reviewed when the template is adopted. 템플릿을 받아 쓸 때 다시 검토한다. GitHub dependency review도 새로 들어온 runtime 의존성에 같은 High
GitHub dependency review applies the same High threshold to newly introduced runtime dependencies. 기준을 쓴다.
The Trivy JSON snapshot is also compared with the CISA Known Exploited Vulnerabilities catalog. Trivy JSON 스냅숏은 CISA KEV(Known Exploited Vulnerabilities, 실제 악용이 확인된 취약점) 목록과도
Any intersection blocks regardless of Trivy severity. Before intersection, CI requires nonblank 대조한다. 겹치는 항목이 있으면 Trivy 심각도와 상관없이 막는다. 대조하기 전에 CI는 KEV 목록을 확인한다.
catalog metadata, a positive integral declared count, a non-empty vulnerability array whose length
matches that count, and unique CVE-pattern `cveID` values. A missing, empty, malformed,
count-inconsistent, duplicate, or unreachable KEV feed fails closed; configure the `KEV_FEED_URL`
repository variable to an approved internal mirror when direct CISA access is unavailable.
Candidate extraction also validates Trivy's JSON first: the top level must be an object with a - 목록 메타데이터가 비어 있지 않다.
non-empty `Results` array; each result is an object whose `Vulnerabilities` value is null or an - 선언한 개수가 양의 정수다.
array; and every listed vulnerability has a nonblank string `VulnerabilityID`. Invalid scanner - 취약점 배열이 비어 있지 않고 길이가 선언한 개수와 같다.
output fails closed instead of becoming an empty candidate set. - `cveID` 값이 CVE 형식이고 서로 다르다.
## Scanner and network requirements KEV 목록이 없거나, 비었거나, 형식이 깨졌거나, 개수가 맞지 않거나, 중복이 있거나, 받을 수 없으면 실패한다
(fail closed). CISA에 직접 닿을 수 없으면 저장소 변수 `KEV_FEED_URL`을 승인된 내부 mirror로 설정한다.
Trivy scans the committed filesystem and Gradle lockfiles. High/Critical findings exit non-zero; 후보를 뽑을 때도 Trivy JSON을 먼저 검사한다. 맨 위가 객체이고 `Results` 배열이 비어 있지 않아야 한다.
Medium/Low findings are reported with exit zero. Scanner database or tool-download failures remain 각 결과는 객체이고, `Vulnerabilities` 값은 null이거나 배열이다. 나열된 취약점마다 비어 있지 않은 문자열
failures rather than silently producing an empty result. `VulnerabilityID`가 있어야 한다. 스캐너 출력이 잘못됐으면 빈 후보 목록으로 넘어가지 않고 실패한다.
Runners need HTTPS egress to: ## 스캐너와 네트워크 요구사항
- the configured Trivy binary source (GitHub Releases by default); Trivy는 커밋된 파일 시스템과 Gradle lockfile을 검사한다. High/Critical이 나오면 0이 아닌 코드로 끝나고,
- Trivy vulnerability databases (the scanner defaults, commonly OCI registries); Medium/Low는 보고만 하고 0으로 끝난다. 스캐너 DB나 도구를 받지 못하면 빈 결과가 아니라 실패다.
- jq releases, unless `JQ_DOWNLOAD_BASE_URL` points to an internal mirror;
- the CISA KEV feed, unless `KEV_FEED_URL` points to an internal mirror;
- GitHub action sources when the forge does not mirror actions.
Closed networks must mirror the pinned Trivy/jq artifacts and checksums, set runner는 다음 곳으로 HTTPS로 나갈 수 있어야 한다.
`TRIVY_DOWNLOAD_BASE_URL` and `JQ_DOWNLOAD_BASE_URL`, configure Trivy's documented database mirror
environment, and set `KEV_FEED_URL`. Mirror availability and freshness are operational
dependencies; stale mirrors can delay detection.
## Suppression governance - 설정한 Trivy 실행 파일 출처(기본은 GitHub Releases)
- Trivy 취약점 DB(스캐너 기본값, 보통 OCI 레지스트리)
- jq 릴리스(`JQ_DOWNLOAD_BASE_URL`이 내부 mirror를 가리키면 그쪽)
- CISA KEV 목록(`KEV_FEED_URL`이 내부 mirror를 가리키면 그쪽)
- forge가 action을 mirror하지 않으면 GitHub action 출처
The only suppression source is repository-root `.trivyignore.yaml`. Every Trivy scan passes it 닫힌 네트워크에서는 고정한 Trivy·jq 산출물과 체크섬을 mirror하고, `TRIVY_DOWNLOAD_BASE_URL`과
explicitly with `--ignorefile .trivyignore.yaml`. Each future entry must contain an identifier, a `JQ_DOWNLOAD_BASE_URL`을 설정하고, Trivy 문서에 있는 DB mirror 환경을 설정하고, `KEV_FEED_URL`을 설정한다.
non-empty rationale, and a future expiry no more than 90 days away. A CODEOWNERS reviewer validates mirror가 살아 있고 최신인지는 운영이 챙길 의존이다. 낡은 mirror는 탐지를 늦출 수 있다.
the shape and expiry; CODEOWNERS plus branch protection controls who may approve the change.
Neither control substitutes for the other.
Do not use an ad-hoc ignore file or an inline scanner bypass. An expired suppression is removed or ## 예외(suppression) 관리
renewed with fresh owner review and current evidence.
## Dependency update policy 예외의 출처는 저장소 루트 `.trivyignore.yaml` 하나다. 모든 Trivy 검사가 `--ignorefile .trivyignore.yaml`로
그 파일을 명시한다. 앞으로 더하는 항목마다 식별자, 비어 있지 않은 이유, 90일 안의 미래 만료일이 있어야
한다. CODEOWNERS 리뷰어가 모양과 만료일을 확인하고, CODEOWNERS와 branch protection이 누가 그 변경을 승인할
수 있는지 정한다. 둘 중 하나가 다른 하나를 대신하지 않는다.
Renovate is the checked-in security-update bot configuration. Patch/pin/digest security updates 임시 ignore 파일이나 스캐너를 건너뛰는 인라인 옵션을 쓰지 않는다. 만료된 예외는 지우거나, 소유자가 새로
may auto-merge only after every configured required check succeeds; minor and major updates require 검토하고 지금의 증거를 붙여 갱신한다.
human review. Dependency declarations and all 19 `gradle.lockfile` files must move together, and
`verifyDependencyLocks` remains release-blocking.
Bot alerts are not a transitive-dependency backstop on every forge. Use a Gradle constraint or ## 의존성 갱신 정책
resolution rule for a vulnerable transitive dependency, refresh locks deliberately, and retain the
full-snapshot Trivy scan. Renovate가 저장소에 커밋된 보안 갱신 봇 설정이다. 보안 갱신은 갱신 종류와 상관없이 자동 병합하지 않는다
(`renovate.json`의 `automerge: false`). Renovate는 strict lockfile을 다시 만들지 않는다. 관리자가
`cd src && ./gradlew resolveAndLockAll --write-locks`로 잠금을 다시 만들고, 잠금 diff를 검토해 함께
커밋한다. 의존성 선언과 모든 `gradle.lockfile`은 같이 움직이고, `verifyDependencyLocks`는 계속 릴리스를
막는다.
봇 알림은 모든 forge에서 전이 의존성(transitive dependency)까지 봐 주지 않는다. 취약한 전이 의존성은
Gradle constraint나 resolution rule로 고정하고, 잠금을 의도적으로 다시 만들고, 전체 스냅숏 Trivy 검사를
유지한다.
+12 -13
View File
@@ -1,18 +1,17 @@
## What changed and why ## 무엇을 왜 바꿨나
<!-- Summarize the behavior, architecture boundary, or policy being changed. --> <!-- 바꾼 동작, 아키텍처 경계, 정책을 요약한다. -->
## Verification ## 검증
- [ ] I ran focused `:<changed-leaf>:check` tasks for the modules I changed. - [ ] 바꾼 모듈마다 `:<changed-leaf>:check`를 돌렸다.
- [ ] I ran `cd src && ./gradlew architectureCheck verifyPublicPathSnapshot verifyDependencyLocks` when the change touched repository structure, dependencies, or public paths. - [ ] 저장소 구조·의존성·공개 경로를 건드렸으면 `cd src && ./gradlew architectureCheck verifyPublicPathSnapshot verifyDependencyLocks`를 돌렸다.
- [ ] I did not add an unregistered production module dependency. - [ ] registry에 없는 production 모듈 의존을 더하지 않았다.
- [ ] Dependency changes include refreshed `gradle.lockfile` files and a strict-lock verification. - [ ] 의존성을 바꿨으면 다시 만든 `gradle.lockfile`과 strict lock 검증을 함께 넣었다.
- [ ] Trivy suppressions include an owner-reviewed reason and an expiry within 90 days. - [ ] Trivy 예외(suppression)에는 소유자가 검토한 이유와 90일 안의 만료일이 있다.
- [ ] Any quarantined test is registered in `flaky-quarantine.yaml` with a reason, issue, and - [ ] 간헐 실패 테스트는 격리하지 않고 고치거나 지웠다(격리 레지스트리는 없다).
`quarantined_since` date. - [ ] 돌리지 못한 검사와 그 때문에 남은 위험을 적었다.
- [ ] I documented checks that could not run and their remaining risk.
## Compatibility and operations ## 호환성과 운영
<!-- Note public API/config changes, migration needs, rollout/rollback impact, and external blockers. --> <!-- 공개 API·설정 변경, 마이그레이션 필요 여부, 배포·되돌리기 영향, 외부 차단 요인을 적는다. -->
+13
View File
@@ -0,0 +1,13 @@
# lychee 링크 검사가 건너뛸 URL. 한 줄에 정규식 하나다. lychee가 저장소 루트에서 이 파일을 읽는다.
# 기록 문서 docs/design, docs/history, docs/reviews 안의 죽은 외부 링크만 여기에 더한다.
# 기록 본문은 고치지 않으니 링크 대신 이 목록을 고친다. 살아 있는 문서의 죽은 링크는 문서를 고친다.
# 규칙은 docs/README.md 문서 검사 절이다.
# docs/design/2026-07-26-production-capability-platform-design.md
^https://www\.mongodb\.com/docs/manual/reference/write-concern/index\.html$
# docs/design/2026-07-28-notification-production-capability-design.md
^https://docs\.aws\.amazon\.com/ses/latest/APIReference-V2/API_SendEmail\.html/$
# docs/design/2026-07-28-notification-production-capability-design.md
^https://docs\.aws\.amazon\.com/sdk-for-java/latest/developer-guide/credentials-chain\.html/$
# docs/reviews/2026-08-14-graphql-module-code-review.md
^https://docs\.spring\.io/spring-graphql/reference/1\.3/request-execution\.html$
+1 -1
View File
@@ -81,7 +81,7 @@ root `CLAUDE.md`는 작업을 시작할 때 읽는 지도이고, 이 목록을
테스트 전에 실패한다. skip된 테스트가 하나라도 있어도 실패한다(`rejectSkipped`를 따로 쓰지 않아도). 테스트 전에 실패한다. skip된 테스트가 하나라도 있어도 실패한다(`rejectSkipped`를 따로 쓰지 않아도).
사람이 손으로 돌리는 `./gradlew performanceCheck`와 workflow가 같은 상한을 단언한다. 사람이 손으로 돌리는 `./gradlew performanceCheck`와 workflow가 같은 상한을 단언한다.
- `verifyEnvKeys`는 app-bootstrap 태스크로 유지한다(2026-09-25 소유자 결정). 구현은 build-logic의 - `verifyEnvKeys`는 app-bootstrap 태스크로 유지한다(2026-09-25 소유자 결정). 구현은 build-logic의
`ca.config-contract`다. `src/build-tools/` included build는 비워서 삭제했다. `ca.config-contract`다. 옛 included build `build-tools`는 지웠다(`docs/capability-status.md` 「제거된 코드」).
- `src/build.gradle`: 루트 라이프사이클(`ci`, `mainCheck`, `integrationCheck`, `performanceCheck`, - `src/build.gradle`: 루트 라이프사이클(`ci`, `mainCheck`, `integrationCheck`, `performanceCheck`,
`releaseCheck`, `qualityCheck`, `configContractCheck`)과 버전/리비전. `verifyStrictLaneStages `releaseCheck`, `qualityCheck`, `configContractCheck`)과 버전/리비전. `verifyStrictLaneStages
--dry-run`(PR 게이트)은 그 빌드에서 `explicitOnly`가 아닌 strict lane이 workflow가 실제로 실행하는 --dry-run`(PR 게이트)은 그 빌드에서 `explicitOnly`가 아닌 strict lane이 workflow가 실제로 실행하는
+89 -115
View File
@@ -1,161 +1,135 @@
# ca-skeleton — Clean Architecture Spring Boot 템플릿 # ca-skeleton — Clean Architecture Spring Boot 백엔드 템플릿
ca-skeleton은 Java 21과 버전 카탈로그에 고정된 Spring Boot 4.x, Gradle 멀티모듈 기반의 Clean Architecture 백엔드 템플릿입니다. fork해서 도메인·패키지·엔티티·유스케이스만 교체하면 새 서비스를 시작할 수 있고, 모듈 경계와 의존 방향은 그대로 유지합니다. 기본 패키지는 `dev.caskeleton`입니다. 업무 기능의 예시는 생성 명령 `scripts/new-feature.sh`의 출력과 [docs/manual/](docs/manual/README.md)입니다. ca-skeleton은 Java 21과 Spring Boot로 만든 Gradle 멀티모듈 백엔드 템플릿이다. 새 서비스를 만드는 개발자가 이 저장소를 복사하고, 도메인·유스케이스·adapter만 채운다. 모듈 경계와 의존 방향은 그대로 둔다. 사람과 AI 세션이 같은 규칙(`AGENTS.md`)과 같은 절차(`docs/work/`)로 일한다. 라이브러리 버전은 `src/gradle/libs.versions.toml`이 정한다.
이 문서는 전체 구조와 첫 실행만 다룹니다. 모듈별 상세 규칙과 설계 근거는 각 모듈의 README와 `CLAUDE.md`가, 빌드·환경 변수 상세는 [src/README.md](src/README.md)가 소유합니다. ## 프로젝트 구조
## 아키텍처 한눈에 저장소 루트에는 정해진 것만 둔다. 허용 목록 밖의 최상위 항목은 `scripts/check-repo-layout.py`가 PR에서 막는다.
의존은 항상 바깥에서 안으로 흐릅니다. adapter가 core의 port에 의존하고, core는 adapter를 알지 못합니다. 이 방향이 유지되는 한 도메인 규칙과 기술 선택(웹 프레임워크, DB, 메시징)을 서로 독립적으로 바꿀 수 있습니다. | 폴더 | 하는 일 | 먼저 읽을 곳 |
| --- | --- | --- |
| `src/` | Gradle 루트. 모든 코드, 빌드 규칙, registry | [src/README.md](src/README.md) |
| `docs/` | 문서. 매뉴얼·계약·운영 문서·결정 기록·기록 | [docs/README.md](docs/README.md) |
| `scripts/` | Gradle 밖 스크립트. 첫 실행, 새 기능 생성, 저장소 배치·문서 검사 | `scripts/bootstrap-local.sh`, `scripts/new-feature.sh` |
| `compose.yaml` | 개발 환경. 앱 컨테이너와 뒷단 서비스(profile로 고른다) | 파일 머리의 profile 표 |
| `compose/` | `compose.yaml`이 마운트하는 보조 파일(Keycloak realm, Redis ACL, MinIO 초기화) | [compose/redis/acl/README.md](compose/redis/acl/README.md) |
| `.github/` | workflow, 공용 action, PR 양식, 의존성 취약점 정책 | [.github/dependency-vulnerability-policy.md](.github/dependency-vulnerability-policy.md) |
`src/` 아래 폴더는 계층 leaf, 조립, 들여온 제품, Gradle 표준 폴더로 나뉜다. leaf는 Gradle 프로젝트 하나이고, leaf 목록·경로·허용 의존은 registry `src/config/architecture/modules.json`이 정한다.
| 폴더 | 책임 | 기본 조립에 들어가나 |
| --- | --- | --- |
| `domain-core/` | 도메인 모델, 불변식, 도메인 이벤트, port. framework·transport·DB 타입을 쓰지 않는다 | 들어간다 |
| `application-core/` | command, 유스케이스, application 정책, 트랜잭션 port. inbound DTO와 persistence entity를 받지 않는다 | 들어간다 |
| `application-fileserver/`, `application-notification/`, `application-objectstorage/` | capability(부가 기능) 하나의 application 계층 | 그 capability를 켤 때 |
| `shared-contract/` | 저장소 전체의 운영 계약(오류 코드, 로그 키, 런타임 환경). 업무 개념은 두지 않는다 | 들어간다 |
| `adapter/inbound/` | HTTP·gRPC·GraphQL·WebSocket·메시징 수신 경계. DTO, 검증, 인증, 오류 매핑 | `web`만 들어간다 |
| `adapter/outbound/` | port 뒤의 구현: 영속성(JPA·MongoDB), Redis, 메시징, 알림, 객체 저장소, 파일 서버, HTTP client, identifier, 공용 기반(support) | `support`·`identifier`만 들어간다 |
| `composition/` | 조립만 하는 leaf: 서비스 런타임 배선, outbox relay, 멱등성 executor, durable operation, 알림·파일 서버 플랫폼 | `service-runtime`·`outbox-relay`·`idempotency`·`durable-operation`이 들어간다. 뒤의 셋은 필요한 port가 생기기 전에는 아무것도 만들지 않는다 |
| `app-bootstrap/` | Spring Boot 진입점과 조립 루트(composition root, 모든 모듈을 엮는 곳) | 들어간다 |
| `platforms/` | 들여온 제품: `messaging`(메시징 플랫폼), `grpc`·`grpc-advanced`(gRPC 라이브러리, 다른 빌드 `optional-build`) | 들어가지 않는다. adapter를 거쳐서만 닿는다 |
| `build-logic/`, `config/`, `gradle/` | 빌드 규칙(convention plugin), 빌드 전체 도구 설정과 registry, wrapper와 버전 카탈로그 | 빌드 도구 |
의존은 항상 바깥에서 안으로 흐른다. adapter가 core의 port에 의존하고, core는 adapter를 모른다.
```text ```text
app-bootstrap -> adapter:inbound:* -> application-core -> domain-core app-bootstrap ─▶ adapter:inbound:* ─▶ application-core ─▶ domain-core
app-bootstrap -> adapter:outbound:* -> application-core -> domain-core app-bootstrap ─▶ adapter:outbound:* ─▶ application-core ─▶ domain-core
모든 런타임 모듈 -> shared-contract 모든 런타임 모듈 ─▶ shared-contract
``` ```
family 수준의 책임은 다음과 같습니다. 불변식: 도메인 규칙은 `domain-core`와 `application-core`에만 있고, 기술 선택(웹, DB, 메시징)은 adapter에만 있다.
| 모듈 family | 책임 | ## 시작하기
| --- | --- |
| `domain-core` | 순수 도메인 모델·불변식·이벤트·port. 프레임워크·transport·DB·IO 타입 금지 |
| `application-core` | command·유스케이스·application 정책·트랜잭션 port. inbound DTO·persistence entity 금지 |
| `adapter:inbound:*` | HTTP·gRPC·GraphQL·WebSocket transport 경계, DTO·validation·인증·에러 매핑 |
| `adapter:outbound:persistence-*` | JPA/PostgreSQL·MongoDB 영속 구현과 매핑·migration |
| `adapter:outbound:*` | support(공유 베이스)·messaging·cache·notification·object storage·file·HTTP client·identifier 능력을 port 뒤에서 구현. 기본 조립에는 support·identifier만 들어 있고, 나머지는 `app-bootstrap/build.gradle`의 `runtimeOnly` 한 줄로 고릅니다 |
| `shared-contract` | skeleton 전역 운영 계약. business/domain 개념 저장 금지 |
| `app-bootstrap` | Spring Boot entrypoint와 composition root |
등록된 leaf 목록과 각 leaf의 Gradle path·소스 경로·허용 production 의존 edge는 전제는 Temurin 21(`.tool-versions`에 고정)과 Docker Engine 또는 Docker Desktop이다. Gradle은 저장소의 wrapper를 쓴다. 첫 실행 진입점은 하나다.
[src/config/architecture/modules.json](src/config/architecture/modules.json)이 SSOT입니다. focused
test는 해당 Gradle path에서 `./gradlew <gradle-path>:test --console=plain` 형태로 파생하며, root
문서나 기억에서 개별 leaf edge를 추론하지 않습니다.
## 퀵스타트
전제조건은 Temurin 21(루트 [.tool-versions](.tool-versions)에 고정)과 Docker Engine 또는 Docker Desktop입니다. Gradle은 저장소 wrapper를 씁니다. 첫 실행 진입점은 하나입니다.
```bash ```bash
scripts/bootstrap-local.sh scripts/bootstrap-local.sh
``` ```
`scripts/bootstrap-local.sh`는 compile 검사, PostgreSQL Compose 기동, 애플리케이션 이미지 build·기동, `GET /api/healthcheck` HTTP smoke를 순서대로 실행합니다. 쓰는 compose 파일은 저장소 루트의 `compose.yaml` 하나입니다. 각 단계가 `bootstrap N/4` 줄을 찍고 실패하면 그 단계에서 멈추므로 실패 단계가 드러납니다. 기동을 확인하려면 health endpoint를 호출합니다. 이 스크립트는 네 단계를 차례로 돈다: 컴파일, PostgreSQL 기동, 앱 이미지 빌드와 기동, `GET /api/healthcheck` 확인. 단계마다 `bootstrap N/4` 줄을 찍고, 실패하면 그 단계에서 멈춘다. 쓰는 compose 파일은 루트의 `compose.yaml` 하나다.
성공하면 이 명령이 HTTP 200을 돌려준다.
```bash ```bash
curl -fsS http://localhost:8080/api/healthcheck curl -fsS http://localhost:8080/api/healthcheck
``` ```
로컬 스택을 내릴 때는 저장소 루트에서 실행합니다. 내릴 때는 저장소 루트에서 `--profile '*'`를 붙인다. 붙이지 않으면 profile로 띄운 `db` 같은 서비스가 남는다.
```bash ```bash
docker compose --profile '*' down docker compose --profile '*' down
``` ```
`--profile '*'`가 없으면 profile이 달린 `db`가 남습니다. compose는 켜진 profile의 서비스만 내립니다. 환경 변수는 `src/.env`(로컬 실행 입력)와 `src/.env.example`(배포 환경 변수의 복사·검증 계약)에 있다. 키 목록과 설명은 [src/README.md](src/README.md)와 [docs/registries/env-keys.yaml](docs/registries/env-keys.yaml)이다.
Redis·Kafka·MongoDB 같은 뒷단 서비스는 `compose.yaml`의 profile로 고릅니다(`docker compose --profile redis up -d --wait`). profile 목록은 그 파일 머리에 있습니다. ## 기능 켜고 끄기
`src/.env.example`은 배포 환경 변수의 추적 가능한 복사/검증 계약이고 `src/.env`는 로컬 실행 입력입니다. 전체 환경 변수 목록과 조정 시점은 [src/README.md](src/README.md)와 [docs/registries/env-keys.yaml](docs/registries/env-keys.yaml)에 있습니다. 기본 조립(`bootJar`)은 web, 운영 관측(actuator·metrics·tracing·로그), core들, `support`·`identifier`뿐이다. 그래서 DB·Redis·Kafka 없이 뜬다. `cd src && ./gradlew :app-bootstrap:bootRun`으로 바로 실행할 수 있다.
### 기본 조립과 부가 기능 DB, Redis, Kafka, 알림, 파일 서버 같은 부가 기능(capability)은 `src/app-bootstrap/build.gradle`에 주석 처리된 `runtimeOnly` 한 줄씩으로 있다.
기본 조립(`bootJar`)은 web, 관측, `domain-core`·`application-core`·`shared-contract`, support, - 켜기: 그 줄의 주석을 풀고 필요한 env 키를 넣는다. 모듈이 classpath에 있으면 켜진다.
identifier뿐이라 DB·Redis·Kafka 없이 기동합니다. - 끄기: 줄을 지운다. 기능·설정·의존성이 함께 빠진다. 줄을 둔 채 끄려면 그 모듈의 `enabled` 키를 `false`로 둔다.
- 줄마다 필요한 env 키와 끄는 키: [src/README.md](src/README.md) 「기능 추가 = 한 줄 + env」 표.
- 기능마다 조립·검증 상태: [docs/capability-status.md](docs/capability-status.md).
- capability 모듈이 지켜야 하는 규칙: [AGENTS.md](AGENTS.md) 「부가 기능(capability) 모듈 규칙」.
뒷단 서비스는 `compose.yaml`의 profile로 고른다(`docker compose --profile redis up -d --wait`). profile 목록은 그 파일 머리에 있다.
## 문서 지도
모든 문서 폴더의 지도는 [docs/README.md](docs/README.md)다. 무엇을 하려는지에 따라 여기서 시작한다.
| 하려는 일 | 시작할 곳 |
| --- | --- |
| 이 저장소에서 일하기(새 기능, 개선, 조사, 문서, 운영, 일 나누기) | 작업 매뉴얼 [docs/work/README.md](docs/work/README.md). 지도는 [CLAUDE.md](CLAUDE.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/` |
| 왜 이렇게 정했는지 보기 | 결정 기록 `docs/adr/` |
| 예전 설계·계획·리뷰 찾기 | 기록 `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)).
## 검증
명령은 `src/`에서 돌린다. 일상 피드백은 바꾼 leaf 하나와 아키텍처 검사다. leaf의 Gradle 경로는 registry의 `gradle_path`에서 읽는다.
```bash ```bash
cd src cd src
./gradlew :app-bootstrap:bootRun ./gradlew :app-bootstrap:check --console=plain
./gradlew architectureCheck --console=plain
``` ```
DB, Redis, Kafka, 알림, 파일 서버 같은 부가 기능은 `app-bootstrap/build.gradle`에 주석 처리된 `./gradlew test`는 모든 leaf의 `test`를 돌리므로 일상 명령으로 쓰지 않는다. PR·main·태그 단계에서 무엇이 도는지, 바꾼 것에 맞춰 무엇을 더 돌릴지는 [docs/work/reference/gates.md](docs/work/reference/gates.md)가 정한다. 게이트 태스크 하나하나의 설명은 [src/README.md](src/README.md) 「build.gradle — 빌드 / 검증 게이트」다.
`runtimeOnly` 한 줄씩으로 있습니다. 줄의 주석을 풀고 필요한 env를 넣으면 켜지고, 줄을 지우면 사라집니다.
줄마다 필요한 env와 끄는 키는 [src/README.md](src/README.md)의 "기능 추가 = 한 줄 + env" 표에 있습니다.
| 프로파일 | 데이터스토어 (persistence-jpa 줄을 넣었을 때) | 스키마 소유자 | 문서를 고쳤으면 저장소 루트에서 `python3 scripts/check-docs.py`를 돌린다. 규칙은 [docs/README.md](docs/README.md) 「문서 검사」다.
| --- | --- | --- |
| `local` | Compose PostgreSQL (`./gradlew :app-bootstrap:bootRunH2`는 줄 없이도 모듈을 자기 classpath에 올려 H2 in-memory로 실행) | Flyway (H2는 Hibernate `create-drop`) |
| `dev` | PostgreSQL | Flyway |
| `prod` | PostgreSQL | Flyway |
H2 실행은 wiring과 애플리케이션 동작만 검증하고, migration과 vendor 동작은 검증하지 않습니다. 프로파일별 설정은 [src/app-bootstrap/src/main/resources/](src/app-bootstrap/src/main/resources/)의 `application-{local,dev,prod}.yml`이, 상세 설명은 [src/README.md](src/README.md)가 소유합니다. ## 새 서비스로 시작하기
## 새 프로젝트로 시작하기 이 저장소를 새 서비스의 출발점으로 쓸 때의 순서다. 전체 체크리스트는 [AGENTS.md](AGENTS.md) 「템플릿 재사용 체크리스트」다.
이 저장소를 새 서비스의 출발점으로 쓸 때 핵심 단계는 다음과 같습니다. 전체 체크리스트는 [AGENTS.md](AGENTS.md)의 "템플릿 재사용 체크리스트"에 있습니다. 1. `src/settings.gradle`의 `rootProject.name`을 새 서비스 이름으로 바꾼다.
2. 패키지 루트 `dev.caskeleton`을 서비스 패키지로 바꾼다. Java 소스만이 아니라 `AutoConfiguration.imports`·`spring.factories`·빌드 스크립트·설정 파일·생성 명령 템플릿도 이 이름을 쓴다. 바꿀 파일은 이 명령으로 찾는다.
1. [src/settings.gradle](src/settings.gradle)의 `rootProject.name`을 새 서비스 이름으로 바꿉니다.
2. 패키지 루트 `dev.caskeleton`을 조직·서비스 패키지로 바꿉니다. 소스뿐 아니라 빌드·설정 파일의 참조도 함께 바꿔야 `mainClass`·`group`이 어긋나 `bootstrap`이 깨지지 않습니다.
```bash ```bash
cd src git grep -l 'dev\.caskeleton' -- src scripts
find . -type f \( -name '*.java' -o -name '*.gradle' -o -name '*.yml' \) -print0 | xargs -0 sed -i 's/dev.caskeleton/com.yourorg.yourservice/g'
``` ```
애플리케이션 이름 등 나머지 rename 단계는 위 체크리스트를 따릅니다. 3. `CaSkeletonApplication`을 새 애플리케이션 이름으로 바꾼다.
4. 새 업무 기능은 `scripts/new-feature.sh <FeatureName>`으로 만들고 [docs/manual/README.md](docs/manual/README.md) 순서대로 채운다. 모듈 이름과 경계는 그대로 둔다.
5. 쓰는 capability의 `runtimeOnly` 줄만 켠다. 켜지 않은 capability leaf는 산출물에 들어가지 않으니 지우지 않아도 된다.
3. `CaSkeletonApplication`을 새 애플리케이션 이름으로 바꾸고, 목표 도메인의 엔티티·repository port·유스케이스·adapter를 production 모듈에 추가합니다. 새 업무 기능은 `scripts/new-feature.sh <FeatureName>`으로 만듭니다. 복사한 뒤 지워도 되는 것은 템플릿의 기록(`docs/design/`, `docs/history/`, `docs/reviews/`)이다. 서비스의 지금 동작을 설명하지 않는다. 지우면 그 기록을 가리키던 살아 있는 문서가 깨지므로 `python3 scripts/check-docs.py`와 링크 검사([docs/work/reference/gates.md](docs/work/reference/gates.md) 「링크 검사」)로 찾아 고친다. 템플릿을 upstream으로 두고 merge해 받으면 그 폴더에서 충돌이 날 수 있다(`docs/upgrade/2026-11-docs-records.md`).
4. 모듈 이름과 경계는 그대로 유지합니다.
검증은 먼저 composition root의 빠른 테스트와 아키텍처 검사를 확인합니다. 루트에서 이름을 바꾼 뒤에는 위 「검증」의 두 명령과 `./gradlew :app-bootstrap:test --console=plain`을 돌린다.
`./gradlew test`를 호출하면 등록된 모든 하위 프로젝트의 `test`를 실행하므로 일상적인 로컬
피드백 명령으로 사용하지 않습니다. 저장소 전체 qualification은 CI 또는 명시적인 `ci` task가
담당합니다.
```bash ## 규칙과 기여
cd src
./gradlew :app-bootstrap:test
./gradlew architectureCheck
```
병합 전 저장소 전체 검증이 필요하면 `./gradlew ci`를 실행합니다. - 규칙의 정본은 [AGENTS.md](AGENTS.md)다. 「Prime Directive」의 HARD-STOP 조건을 어기면 동작하더라도 병합하지 않는다.
- 일을 시작할 때 읽는 지도는 [CLAUDE.md](CLAUDE.md)다. 일의 종류별 절차는 [docs/work/README.md](docs/work/README.md)다.
## 아키텍처 규칙과 검증 - 각 모듈의 지역 규칙은 가장 가까운 `src/**/CLAUDE.md`다.
- 커밋 정책과 메시지 형식은 [docs/work/README.md](docs/work/README.md) 「커밋」이다. PR은 [.github/pull_request_template.md](.github/pull_request_template.md) 양식을 채운다.
애플리케이션이 동작하더라도 아래를 어기면 병합하지 않습니다. HARD-STOP 7개 조건의 정본 로컬
정책 권위는 [AGENTS.md](AGENTS.md)이며, [CLAUDE.md](CLAUDE.md)는 작업을 시작할 때 읽는 지도입니다.
일의 종류별 절차는 [docs/work/](docs/work/README.md)에 있습니다.
- `domain-core`는 Spring·JPA·Servlet·HTTP·DB·cloud SDK 타입을 import하지 않습니다.
- controller는 repository를 직접 호출하거나 persistence entity를 반환하지 않습니다.
- inbound DTO는 `application-core`나 `domain-core`로 들어가지 않습니다.
- 비즈니스 정책은 mapper·filter·config·settings·controller에 두지 않습니다.
- 새 외부 시스템 연동은 domain/application port와 adapter 모듈로 표현합니다.
이 규칙은 두 축으로 자동 강제합니다. `:app-bootstrap:architectureTest`의 분할된 ArchUnit 규칙들이 컴파일된 소스 의존성을,
`verifyCleanArchitectureDependencies` 게이트가 JSON registry의 허용 Gradle project edge를
검사합니다.
```bash
cd src
./gradlew verifyCleanArchitectureDependencies
```
두 검증 축은 [ci-quality-gates.yml](.github/workflows/ci-quality-gates.yml)의 release gate에 연결되어, 규칙 위반이 병합·릴리스를 막습니다.
## 수동 전용 Gradle 태스크
아래 태스크는 **어떤 워크플로도 실행하지 않으며, 그게 의도다.** 자동 실행이 틀린 이유를 적어 둔다.
여기 적힌 태스크 이름이 실재하는지 검사하던 `verifyReadmeCommands`는 삭제했다. 그건 이 문서의
```bash 블록을 직접 파싱해 `./gradlew`·`docker compose`·`make` 토큰을 실제 태스크 그래프와 대조하는
Markdown 명령 파서였고, 그 결과 "README에 무엇을 쓸 수 있는가"가 그 파서가 읽을 수 있는 문법의
함수가 됐다. 문서와 코드가 어긋나는 것은 결함이지만, 빌드를 실패시켜서 고칠 일은 아니다.
```bash
cd src
./gradlew :grpc:grpc-testkit:grpcPerformanceTest
```
- `grpcPerformanceTest` — latency percentile·saturation·drain budget을 **측정**한다. 공유 CI
runner의 측정값은 흔들리고, 흔들리는 게이트는 결국 꺼진다. leaf `build.gradle`이 이 태스크의
태그를 `test`에서 제외하는 이유도 같다. 성능 회귀가 의심될 때 사람이 이름으로 부른다.
## 더 알아보기
- 빌드·검증 게이트·환경 변수 상세: [src/README.md](src/README.md)
- 모듈 레지스트리(등록 leaf SSOT): [src/config/architecture/modules.json](src/config/architecture/modules.json)
- 에이전트·기여자 작업 규칙: [AGENTS.md](AGENTS.md) · [CLAUDE.md](CLAUDE.md)
- release/publish 자동화는 `.github/workflows/release.yml`이 소유하며, release provenance·SBOM·
이미지 build/push를 해당 workflow의 명시적 권한과 게이트 아래에서 수행합니다.
- 모듈별 설계 결정: [domain-core](src/domain-core/README.md) · [application-core](src/application-core/README.md) · [adapter:inbound:web](src/adapter/inbound/web/README.md) · [adapter:outbound:persistence-jpa](src/adapter/outbound/persistence-jpa/README.md) · [shared-contract](src/shared-contract/README.md) · [app-bootstrap](src/app-bootstrap/README.md)
+25 -29
View File
@@ -1,37 +1,33 @@
# Keycloak realm artifact # Keycloak realm 파일
`realms/ca-skeleton-realm.json` is imported by the `keycloak` service in the root `compose.yaml` 루트 `compose.yaml`의 `keycloak` 서비스가 `realms/ca-skeleton-realm.json`을 가져온다(import). 모든 GraphQL
and is the same realm every GraphQL qualification lane authenticates against. qualification lane이 인증하는 realm도 이 파일이다.
## The client secret is a reference, never a value ## client secret은 값이 아니라 참조다
The confidential client `ca-skeleton-api` carries `"secret": "${KEYCLOAK_GRAPHQL_SMOKE_CLIENT_SECRET}"`. confidential client `ca-skeleton-api`는 `"secret": "${KEYCLOAK_GRAPHQL_SMOKE_CLIENT_SECRET}"`를 가진다.
`entrypoint.sh` reads the value from the Compose secret mounted at `entrypoint.sh`가 `/run/secrets/keycloak-graphql-smoke-client-secret`에 마운트된 Compose secret에서 값을 읽어
`/run/secrets/keycloak-graphql-smoke-client-secret`, exports it, and execs `kc.sh start-dev export하고, `kc.sh start-dev --import-realm`을 exec한다. 그래서 값이 Git, 렌더링된 Compose 설정, 명령줄,
--import-realm`, so the value never reaches Git, a rendered Compose config, a command line, or an 증거 파일 어디에도 닿지 않는다. 동작하는 자격 증명이 든 realm 파일은 저장소 안의 자격 증명이다. 「smoke
evidence file. A realm file with a working credential in it is a credential in the repository, and 테스트에만 쓴다」는 사정은 스캐너도 fork도 알 수 없다.
"it is only for smoke tests" is not something a scanner or a fork can tell.
## No comment keys in the realm JSON ## realm JSON에 주석 키를 두지 않는다
Keycloak deserializes this file into `RealmRepresentation` with unknown fields **rejected**, not Keycloak은 이 파일을 `RealmRepresentation`으로 역직렬화할 때 모르는 필드를 무시하지 않고 **거절한다**.
ignored. A `"_comment"` key here fails the whole import with `Unrecognized field "_comment"`, the `"_comment"` 키 하나가 `Unrecognized field "_comment"`로 import 전체를 실패시키고, 컨테이너가 1로 끝나고,
container exits 1, and the lane fails on Keycloak rather than on anything it was testing. That is lane은 시험하던 것이 아니라 Keycloak에서 실패한다. 그래서 이 근거를 파일 안이 아니라 옆의 Markdown에 둔다.
why this rationale lives in Markdown next to the artifact instead of inside it.
## What the realm grants ## realm이 주는 권한
- realm role `user` — the baseline role the application authorizes ordinary calls on - realm role `user`: 애플리케이션이 보통 호출을 허가하는 기본 role
- client role `ca-skeleton-api:graphql-query` — permission to execute a GraphQL query - client role `ca-skeleton-api:graphql-query`: GraphQL query를 실행할 권한
- client roles `notification-submit`, `notification-template-publish`, `operation-submit` — the - client role `notification-submit`, `notification-template-publish`, `operation-submit`: `security.yml`이
platform permissions `security.yml` maps them to 플랫폼 권한으로 바꾸는 role
- client roles `ROLE_FILE_READ` and `ROLE_FILE_WRITE` — the fileserver's read and write tiers, which - client role `ROLE_FILE_READ`, `ROLE_FILE_WRITE`: 파일 서버의 읽기·쓰기 등급. `security.yml`이 각각
`security.yml` also maps to `file:read` and to `file:upload`, `file:delete`, `file:copy`, `file:read`와 `file:upload`·`file:delete`·`file:copy`·`file:move`로 바꾼다. `ROLE_FILE_ADMIN`
`file:move`; `ROLE_FILE_ADMIN` (`file:admin`) is defined but not granted to the service account, (`file:admin`)은 정의만 하고 service account에 주지 않는다. 관리 기능은 기본으로 꺼져 있다
since the management plane is off by default - qualification lane이 쓰는 client credentials grant용 service account
- a service account for the client-credentials grant the qualification lane uses - audience mapper와 realm·client role mapper. 발급한 토큰에 resource server가 검증하는 값이 실린다
- audience and realm/client role mappers, so the issued token carries what the resource server
validates
Standard flow and direct access grants are disabled: the lane authenticates as a service, and an standard flow와 direct access grant는 꺼 두었다. lane은 서비스로 인증하고, 켜 둔 password grant는 아무도
enabled password grant is a second way in that nothing tests. 시험하지 않는 두 번째 입구가 된다.
+55 -49
View File
@@ -1,58 +1,64 @@
# ACL accounts — test fixtures, not a deployment file # ACL 계정 — 배포 파일이 아니라 시험용 fixture
**Nothing in this directory is loaded by a deployment.** Every file here is a fixture for the local **이 폴더의 어떤 파일도 배포에서 읽지 않는다.** 모든 파일이 로컬·테스트 lane용 fixture다.
and test lanes: its passwords are public (`fixture-*`, written in this repository), and
`lane-fixture-accounts.acl` also provisions three accounts that only a lane topology needs — among
them `ca-skeleton-cluster-bootstrap`, which has `~* &* +@all`, every command on every key. Loaded into
a real Redis, that line alone gives anyone who can reach the server and read this repository full
control of it (`CONFIG`, `MODULE`, every key). A deployment writes its own ACL file of the same
shape: the application accounts it actually uses, passwords from its secret store, and none of the
lane-only accounts (review 2026-11-03 RR-07-04). The application enforces its half of that: under
the `prod` runtime profile it refuses to start while a secret holds a value beginning with
`fixture-` (`SecretSourceValidator`): a key the secrets registry classifies `secret`, a variable a
module's `RequiredProductionSecrets` bean names, or the variable a `secret://…/<VAR>` credential
reference in the environment names. A reference held in code — the typed SDK's admin account,
contributed as a `RedisAccountContribution` bean — is none of those: the composer names its variable
in a `RequiredProductionSecrets` bean too (`src/adapter/outbound/redis-sdk/README.md`), or the
`fixture-admin` password passes. A deployment that copied a lane's
`APP_REDIS_AUTHENTICATION_*_REFERENCE` and `REDIS_LANE_*` values stops before it connects. Values
that are not secrets — a pod's `HOSTNAME`, an application name — are not read, because `fixture-`
is an ordinary word as well.
One file per `CommandAccess` level. Each account is deliberately narrower than the SDK's own rules: - 비밀번호가 공개돼 있다(`fixture-*`, 이 저장소에 적혀 있다).
the account is the last enforcement boundary and a permit issued inside the process never widens it, - `lane-fixture-accounts.acl`은 lane 구성에만 필요한 계정 셋도 만든다. 그중
so a mistake in the SDK is still refused by the server. `ca-skeleton-cluster-bootstrap`은 `~* &* +@all`, 곧 모든 key에 모든 명령을 가진다.
- 이 줄 하나를 실제 Redis에 올리면, 서버에 닿을 수 있고 이 저장소를 읽을 수 있는 누구나 서버 전체
(`CONFIG`, `MODULE`, 모든 key)를 다룰 수 있다.
A Redis ACL file accepts nothing but complete `user` lines — no comments and no line continuations — 배포는 같은 모양의 자기 ACL 파일을 쓴다. 실제로 쓰는 애플리케이션 계정만 두고, 비밀번호는 자기 secret
which is why the rationale lives here instead of inline. store에서 가져오고, lane 전용 계정은 두지 않는다(review 2026-11-03 RR-07-04).
Every account here carries a **fixture** password (`fixture-*`). They are written down rather than 애플리케이션도 자기 몫을 강제한다. `prod` 런타임 profile에서 비밀값이 `fixture-`로 시작하면 기동을
left as `nopass` because an account that accepts any password makes every assertion about 거부한다(`SecretSourceValidator`). 보는 비밀값은 셋이다.
authentication pass for the same reason a typo would have — and because these files are what a fork
copies. The four per-role files carried `nopass` long after the combined lane file had been fixed;
a fork that copied one of them got an open account and a green lane.
| File | Account | Grants | - 비밀 레지스트리가 `secret`으로 분류한 키
- 모듈의 `RequiredProductionSecrets` bean이 이름을 댄 변수
- 환경 안의 `secret://…/<VAR>` 자격 증명 참조가 가리키는 변수
코드에 있는 참조(typed SDK의 admin 계정을 `RedisAccountContribution` bean으로 기여하는 경우)는 이 셋 중
어디에도 들지 않는다. 조립하는 쪽이 그 변수도 `RequiredProductionSecrets` bean에 적어야 한다
(`src/adapter/outbound/redis-sdk/README.md`). 그러지 않으면 `fixture-admin` 비밀번호가 통과한다.
lane의 `APP_REDIS_AUTHENTICATION_*_REFERENCE`와 `REDIS_LANE_*` 값을 복사한 배포는 연결하기 전에 멈춘다.
비밀이 아닌 값(pod의 `HOSTNAME`, 애플리케이션 이름)은 읽지 않는다. `fixture-`는 보통 낱말이기도 하다.
`CommandAccess` 등급마다 파일이 하나다. 각 계정은 SDK 자체 규칙보다 일부러 더 좁다. 계정이 마지막
강제 경계이고 프로세스 안에서 내준 허가는 그 경계를 넓히지 못한다. 그래서 SDK에 실수가 있어도 서버가
거절한다.
Redis ACL 파일은 완전한 `user` 줄만 받는다. 주석도, 줄 이어 쓰기도 안 된다. 그래서 근거를 파일 안이
아니라 여기에 둔다.
여기의 모든 계정은 **fixture** 비밀번호(`fixture-*`)를 가진다. `nopass`로 두지 않고 적어 둔 이유는 둘이다.
- 아무 비밀번호나 받는 계정에서는 인증에 대한 모든 단언이 오타가 있어도 통과한다.
- fork가 복사하는 것이 이 파일들이다. 역할별 파일 넷은 합친 lane 파일을 고친 뒤에도 오래 `nopass`였고,
그중 하나를 복사한 fork는 열린 계정과 녹색 lane을 함께 얻었다.
| 파일 | 계정 | 주는 권한 |
| --- | --- | --- | | --- | --- | --- |
| `application.acl` | `CommandAccess.APPLICATION` | the typed data-structure commands over `prod:*`, with the dangerous and deprecated names denied | | `application.acl` | `CommandAccess.APPLICATION` | `prod:*` 위의 typed 자료구조 명령. 위험한 명령과 폐기된 명령 이름은 막는다 |
| `application-advanced.acl` | `APPLICATION_ADVANCED` | the above plus pub/sub, transactions, and the registered-script path. `EVAL` is absent: only `EVALSHA` of an already loaded digest is reachable. `+time` is granted because the rate-limit and idempotency scripts read the server clock with `redis.call('TIME')`, and `TIME` is in no data category (`@read`/`@write`): without it every such script fails with an ACL error. The startup SCRIPT probe runs `TIME` so a template missing it fails at boot | | `application-advanced.acl` | `APPLICATION_ADVANCED` | 위 권한에 pub/sub, 트랜잭션, 등록된 script 경로를 더한다. `EVAL`은 없다: 이미 올린 digest의 `EVALSHA`만 닿는다. `+time`을 주는 이유: rate-limit·idempotency script가 `redis.call('TIME')`으로 서버 시계를 읽는데, `TIME`은 어떤 데이터 범주(`@read`/`@write`)에도 없다. 없으면 그런 script가 모두 ACL 오류로 실패한다. 기동 때의 SCRIPT 확인이 `TIME`을 돌려서, 이 권한이 빠진 템플릿은 기동에서 실패한다 |
| `raw-gateway.acl` | `RAW_GATEWAY` | exactly the commands the catalog classifies `RAW_ONLY`, and nothing else | | `raw-gateway.acl` | `RAW_GATEWAY` | catalog가 `RAW_ONLY`로 분류한 명령만, 그 밖에는 없다 |
| `lane-fixture-accounts.acl` | – | what the lanes load (Redis takes one `aclfile`): `user default off`, the four per-role accounts of this table, and three lane-only accounts — `ca-skeleton-replication` (replica sync) and `ca-skeleton-sentinel` for the replicated and sentinel topologies, `ca-skeleton-cluster-bootstrap` (`+@all`) to create the cluster lane's slots. Never a deployment file | | `lane-fixture-accounts.acl` | – | lane이 읽는 파일(Redis는 `aclfile` 하나만 받는다): `user default off`, 이 표의 역할별 계정 넷, lane 전용 계정 셋 — `ca-skeleton-replication`(replica 동기화)과 `ca-skeleton-sentinel`(replicated·sentinel 구성용), `ca-skeleton-cluster-bootstrap`(`+@all`, cluster lane의 slot을 만든다). 배포 파일이 아니다 |
| `admin-readonly.acl` | `ADMIN_READONLY` | read-only diagnostics. Every destructive counterpart is denied here and blocked in the command policy catalog — two independent controls for the same rule | | `admin-readonly.acl` | `ADMIN_READONLY` | 읽기 전용 진단. 파괴적인 짝 명령은 모두 여기서 막고 명령 정책 catalog에서도 막는다 — 같은 규칙에 서로 독립인 통제 둘 |
| `sentinel-accounts.acl` | – | sentinel 프로세스용 계정(`ca-skeleton-sentinel-client`, `ca-skeleton-sentinel-peer`, `ca-skeleton-sentinel-operator`). 지금 이 파일을 `aclfile`로 읽는 compose 파일은 없다 |
## Who loads `lane-fixture-accounts.acl` ## 누가 `lane-fixture-accounts.acl`을 읽나
The Redis topology lanes (`src/adapter/outbound/redis-sdk/compose/{standalone,sentinel,cluster,tls}`), the - Redis 구성(topology) lane: `src/adapter/outbound/redis-sdk/compose/{standalone,sentinel,cluster,tls}`
application's Compose lanes that switch Redis on (`local-redis`, `all-adapters` in - Redis를 켜는 애플리케이션 Compose lane: `src/app-bootstrap/compose-lanes/compose-profile-contracts.json`의
`src/app-bootstrap/compose-lanes/compose-profile-contracts.json`), and the development stack's `local-redis`, `all-adapters`
`redis` service (root `compose.yaml`). They all mount this directory read-only; neither - 개발 환경의 `redis` 서비스(루트 `compose.yaml`)
keeps a copy, because a second copy of these lines is a second place for a password or a key
pattern to drift.
The Compose lanes connect the application as `ca-skeleton-application` and 모두 이 폴더를 읽기 전용으로 마운트한다. 복사본을 두지 않는다. 이 줄들의 두 번째 사본은 비밀번호나 key
`ca-skeleton-application-advanced`, through `secret://<account>@environment/<variable>` references 패턴이 따로 어긋날 두 번째 자리다.
whose variables carry the fixture passwords above. They run with the Redis namespace environment
`prod`, because every account here is fenced to `~prod:*`. `scripts/verify-compose-profile-contracts.sh` Compose lane은 애플리케이션을 `ca-skeleton-application`과 `ca-skeleton-application-advanced`로 연결한다.
compares each Redis lane's references, passwords and namespace with the account lines in this file, 연결은 `secret://<account>@environment/<variable>` 참조를 거치고, 그 변수가 위 fixture 비밀번호를 가진다.
so changing a password or a key pattern here without the lanes fails that check rather than the 여기의 모든 계정이 `~prod:*`로 묶여 있어서, lane은 Redis namespace 환경을 `prod`로 두고 돈다.
lane's first command. `scripts/verify-compose-profile-contracts.sh`가 Redis lane마다 참조·비밀번호·namespace를 이 파일의 계정 줄과
비교한다. 그래서 lane을 고치지 않고 여기의 비밀번호나 key 패턴만 바꾸면, lane의 첫 명령이 아니라 그 검사가
실패한다.
+96 -40
View File
@@ -1,60 +1,107 @@
# docs # docs
저장소의 모든 문서는 이 디렉터리 아래에 있다. 규칙은 둘이다: 어떤 문서를 어디에 두는지(아래 표), 저장소의 모든 문서는 이 폴더 아래에 있다. 이 README는 두 가지를 정한다.
문서의 수명에 따라 무엇을 어떤 언어로 고치는지(「문서 수명과 언어」). 파일 목록은 디렉터리를 직접 읽는다.
개수를 여기에 적으면 다음 문서가 추가되는 순간 틀린 글이 된다.
## 어댑터별 운영 문서 - 어떤 문서가 어느 폴더에 있나: 아래 「문서 지도」. 지금 있는 모든 문서 폴더를 덮는다.
- 문서의 수명에 따라 무엇을 어떤 언어로 고치나: 「문서 수명과 언어」.
각 어댑터의 지원 범위, 설정, 보안, 운영, 마이그레이션 문서다. 코드와 함께 갱신되어야 하는 문서이고, 파일 목록과 개수는 여기에 적지 않는다. 적으면 다음 문서가 더해지는 순간 틀린 글이 된다. 파일은 폴더를 직접 읽는다.
`docs/httpclient/` 는 `scripts/verify-httpclient-docs.py` 가 코드에서 뽑은 이름과 대조한다.
| 디렉터리 | 대상 | ## 문서 지도
- 표의 첫 칸이 폴더다(`docs/` 기준 경로).
- 새 문서 폴더를 만들면 같은 변경에서 이 지도에 행을 더한다. 폴더를 지우거나 옮기면 그 행도 고친다.
- `python3 scripts/check-docs.py`의 `map` 검사가 지도에 없는 폴더와, 지도에 있지만 없는 폴더를 막는다(「문서 검사」).
### 매뉴얼
일하는 순서와 판단 지점이다. 사람과 AI 세션이 같이 쓴다.
| 폴더 | 무엇 |
| --- | --- | | --- | --- |
| `fileserver/` | 파일 서버 어댑터 | | `work/` | 작업 매뉴얼: 이 repo에서 하는 일(새 기능, 개선, 조사·설계, 문서 작성, 운영, 일 나누기)의 절차서. 루트 `CLAUDE.md` 다음에 읽는다 |
| `httpclient/` | HTTP 클라이언트 플랫폼 |
| `jpa/` | JPA·PostgreSQL 영속성 |
| `messaging/` | 메시징 어댑터 |
| `mongodb/` | MongoDB 문서 영속성 (`advanced/`, `runbooks/` 포함) |
| `notification/` | 알림 전달 플랫폼 (`adr/` 포함) |
| `redis/` | Redis 캐시·세션 |
## 횡단 문서
| 디렉터리 | 대상 |
| --- | --- |
| `adr/` | 아키텍처 결정 기록 |
| `architecture/` | 공개 API 표면 스냅숏 |
| `work/` | 작업 매뉴얼: 이 repo에서 하는 일(새 기능, 개선, 조사·설계, 문서 작성, 운영, 총괄)의 절차서. 루트 `CLAUDE.md` 다음에 읽는다 |
| `manual/` | 개발 매뉴얼: 새 기능을 만드는 순서와 판단 지점, 생성 명령(`scripts/new-feature.sh`). 입구는 `work/new-feature.md` | | `manual/` | 개발 매뉴얼: 새 기능을 만드는 순서와 판단 지점, 생성 명령(`scripts/new-feature.sh`). 입구는 `work/new-feature.md` |
| `registries/` | env 키·에러 코드·메트릭·헤더 등 레지스트리 SSOT | | `testing/` | 테스트 전략: 테스트 종류 다섯, source set, 어떤 테스트를 어디에 두나, Gradle 실행 계층 |
| `reviews/` | 모듈 코드 리뷰 결과 |
| `runbooks/` | 장애 코드별 대응 런북 (`template.md` 기준) |
| `security/` | 공개 경로 스냅숏 |
## 설계와 기록 ### 계약과 스냅숏
코드와 테스트가 대조하는 정본이다. 바꾸면 공개 계약이 바뀔 수 있다(`work/README.md` 2절).
| 폴더 | 무엇 |
| --- | --- |
| `registries/` | 레지스트리: env 키, 오류 코드, 메트릭, HTTP 헤더, 로그(MDC) 키, 비밀 분류, use case capability, 객체 저장소 준비도. 테스트가 코드와 대조한다 |
| `web/` | HTTP wire 계약(`web/http-contract.md`), PATCH·스트리밍 계약, 선택형 web 기능(`web-advanced`), web 장애 대응 |
| `architecture/` | 공개 API 표면 스냅숏(`*-api-surface.txt`). API surface 검사가 대조한다 |
| `security/` | 기본 공개 경로 스냅숏. `verifyPublicPathSnapshot`이 대조한다 |
| `observability/` | 구조화 로그 필드 사전 |
| `compatibility/` | gRPC 플랫폼 지원 매트릭스(무엇에 대해 인증했고 무엇은 지켜보기만 하나) |
### 영역 운영 문서
capability(부가 기능) 하나의 지원 범위, 설정, 보안, 운영, 마이그레이션이다. 코드와 같은 변경에서 고친다.
`httpclient/`는 `scripts/verify-httpclient-docs.py`가 코드에서 뽑은 이름과 대조한다.
| 폴더 | 무엇 |
| --- | --- |
| `fileserver/` | 파일 서버 |
| `httpclient/` | 외부 HTTP 호출(HTTP client 플랫폼) |
| `jpa/` | JPA·PostgreSQL 영속성 |
| `messaging/` | 메시징 adapter |
| `mongodb/` | MongoDB 문서 영속성 |
| `mongodb/advanced/` | MongoDB 고급 기능(암호화, 멀티 테넌시, 샤딩). 설정 키가 아니라 라이브러리 API로 켠다 |
| `mongodb/runbooks/` | MongoDB 장애 대응 |
| `mongo/` | MongoDB 영속성 설정 예시 파일(Spring이 읽지 않는 예시) |
| `notification/` | 알림 전달 플랫폼 |
| `objectstorage/` | 객체 저장소의 설정 필드와 env 이름 표(`env-fields.yaml`) |
| `redis/` | Redis 캐시·세션 |
| `websocket/` | WebSocket handler 장애 대응 |
### 운영과 전달
| 폴더 | 무엇 |
| --- | --- |
| `runbooks/` | 오류 코드별 장애 대응 런북(`runbooks/template.md` 형식) |
| `ci-cd/` | CI/CD 경계: 검증·빌드(CI)와 배포(CD)의 경계, 템플릿과 파생 서비스가 각각 돌릴 검증 |
| `upgrade/` | 파생 서비스용 변경 안내: 템플릿 변경을 받을 때 서비스가 할 일 |
| `roadmap/` | 아직 구현하지 않은 다음 단계와 그 조건 |
### 결정 기록
| 폴더 | 무엇 |
| --- | --- |
| `adr/` | 결정 기록(ADR). 영역마다 파일 이름 앞머리가 다르다(`ADR-JPA-`, `NOTIF-ADR-` 등) |
### 설계와 기록
설계서와 기록은 쓴 때의 글이다. 지금 동작을 설명하지 않는다. 그래서 살아 있는 문서와 다른 폴더에 둔다. 설계서와 기록은 쓴 때의 글이다. 지금 동작을 설명하지 않는다. 그래서 살아 있는 문서와 다른 폴더에 둔다.
| 디렉터리 | 대상 | | 폴더 | 무엇 |
| --- | --- | | --- | --- |
| `design/` | 설계서. `YYYY-MM-DD-<주제>-design.md` | | `design/` | 설계서. `YYYY-MM-DD-<주제>-design.md` |
| `history/plans/` | 구현·확장 계획서. `YYYY-MM-DD-<주제>-plan.md` | | `history/plans/` | 구현·확장 계획서. `YYYY-MM-DD-<주제>-plan.md` |
| `history/packages/` | 외부에서 납품된 설계 패키지의 README와 정적 검증 결과 | | `history/packages/` | 외부에서 납품된 설계 패키지의 README와 정적 검증 결과 |
| `history/evidence/` | 작업 단계별 증거·체크포인트 | | `history/evidence/` | 작업 단계별 증거·체크포인트 |
| `history/study/` | 학습 문서. 쓴 때의 코드를 따라 읽은 기록이다 | | `history/study/` | 학습 문서. 쓴 때의 코드를 따라 읽은 기록이다 |
| `reviews/` | 코드 리뷰 결과. 라운드마다 폴더 하나(README가 결정과 남은 것을 적는다) 또는 리뷰 문서 하나 |
`history/packages/<어댑터>/` 는 설계서가 처음 전달됐을 때의 안내와 `VALIDATION.md` 검증 이력을 `history/packages/<어댑터>/`는 설계서가 처음 전달됐을 때의 안내와 `VALIDATION.md` 검증 이력을
남긴 기록 보관소다. 설계서·계획서 본문은 전부 `design/` 과 `history/plans/` 에 있으므로 이 디렉터리에서 남긴 기록 보관소다. 설계서·계획서 본문은 전부 `design/`과 `history/plans/`에 있으므로 이 폴더에서
문서를 찾을 필요는 없다. 각 README 상단의 보존 안내가 무엇이 옮겨졌고 무엇이 제거됐는지 밝힌다. 문서를 찾을 필요는 없다. 각 README 상단의 보존 안내가 무엇이 옮겨졌고 무엇이 제거됐는지 밝힌다.
`history/packages/*-superpowers-package/` 셋은 납품된 묶음 그대로이고, 그 안의 `MANIFEST.sha256` 은 `history/packages/*-superpowers-package/` 셋은 납품된 묶음 그대로이고, 그 안의 `MANIFEST.sha256`은
납품 당시 바이트의 해시다. 납품 당시 바이트의 해시다.
계획서 본문에는 당시 계획한 경로와 명령이 그대로 남아 있다. 그중 일부는 실제 구현에서 다른 위치로 계획서 본문에는 당시 계획한 경로와 명령이 그대로 남아 있다. 그중 일부는 실제 구현에서 다른 위치로
조정됐고, 저장소에 어떻게 대응시켰는지는 각 어댑터의 `repository-adaptation.md` 또는 조정됐고, 저장소에 어떻게 대응시켰는지는 각 어댑터의 `repository-adaptation.md` 또는
`module-mapping.md` 가 기록한다. 계획서를 사후에 고치지 않는 이유는 그렇게 하면 계획의 기록이 아니라 `module-mapping.md`가 기록한다. 계획서를 나중에 고치지 않는 이유는 그렇게 하면 계획의 기록이 아니라
결과를 계획처럼 보이게 만든 글이 되기 때문이다. 결과를 계획처럼 보이게 만든 글이 되기 때문이다.
### 폴더 밖 문서
| 문서 | 무엇 |
| --- | --- |
| [capability-status.md](capability-status.md) | capability마다 코드가 있나·조립되나·실제 제공자로 검증됐나, 그리고 지운 코드의 표(「제거된 코드」) |
| [storage-capability-boundary.md](storage-capability-boundary.md) | 파일 서버와 객체 저장소가 각각 맡는 경계 |
## 문서 수명과 언어 ## 문서 수명과 언어
규칙의 정본은 design-docs `conventions/docs-system.md`다. 이 절은 이 repo에 적용한 내용이고, 규칙의 정본은 design-docs `conventions/docs-system.md`다. 이 절은 이 repo에 적용한 내용이고,
@@ -63,17 +110,19 @@
| 수명 | 문서 | 위치 | 언어 | 고치는 법 | | 수명 | 문서 | 위치 | 언어 | 고치는 법 |
| --- | --- | --- | --- | --- | | --- | --- | --- | --- | --- |
| 살아 있음 | README, `CLAUDE.md`, `AGENTS.md`, 매뉴얼(`manual/`, `work/`), 영역 운영 문서, `registries/`, `runbooks/`, `upgrade/` | 제자리 | 한국어 | 코드와 같은 변경에서 고친다 | | 살아 있음 | README, `CLAUDE.md`, `AGENTS.md`, 매뉴얼(`manual/`, `work/`), 영역 운영 문서, `registries/`, `runbooks/`, `upgrade/` | 제자리 | 한국어 | 코드와 같은 변경에서 고친다 |
| 결정 | 결정 기록(ADR) | `adr/`, `notification/adr/` | 한국어 | 본문은 고치지 않는다. 일부가 바뀌면 상태를 「채택(보완)」으로 하고 보완 절을 덧붙인다. 크게 바뀌면 새 ADR을 쓰고 옛 ADR을 「대체됨」으로 한다 | | 결정 | 결정 기록(ADR) | `adr/` | 한국어 | 본문은 고치지 않는다. 일부가 바뀌면 상태를 「채택(보완)」으로 하고 보완 절을 덧붙인다. 크게 바뀌면 새 ADR을 쓰고 옛 ADR을 「대체됨」으로 한다 |
| 기록 | 설계서, 계획서, 납품 패키지, 증거, 학습 문서, 리뷰 | `design/`, `history/`, `reviews/` | 머리 블록은 한국어, 본문은 쓴 때의 원문 | 머리 블록의 칸만 고친다 | | 기록 | 설계서, 계획서, 납품 패키지, 증거, 학습 문서, 리뷰 | `design/`, `history/`, `reviews/` | 머리 블록은 한국어, 본문은 쓴 때의 원문 | 머리 블록의 칸만 고친다 |
- 코드 식별자, 명령, 경로, 설정 키, 오류 코드, 로그·출력 인용, 제품 이름은 원문으로 둔다. - 코드 식별자, 명령, 경로, 설정 키, 오류 코드, 로그·출력 인용, 제품 이름은 원문으로 둔다.
- 문체는 「~한다」다. 한 문서 안에서 「~합니다」와 섞지 않는다. - 문체는 「~한다」다. 한 문서 안에서 「~합니다」와 섞지 않는다.
- 아직 한국어로 옮기지 않은 살아 있는 문서와 ADR은 문서 검사의 예외 목록에 있다(「문서 검사」). - 살아 있는 문서와 ADR 본문은 2026-11-07에 모두 한국어로 옮겼다. 문서 검사의 예외 목록은 비어 있다(「문서 검사」).
- ADR 본문의 번역은 뜻을 바꾸지 않은 옮김이다. 옮기기 전 원문은 커밋 `03a313ed`에 있다(알림 ADR은 그때 다른
폴더에 있었다. 옛 경로는 `docs/upgrade/2026-11-docs-records.md`).
## 기록 문서의 머리 블록 ## 기록 문서의 머리 블록
`design/`, `history/`, `adr/`, `notification/adr/`의 `.md` 파일은 맨 위에 이 블록을 둔다. `design/`, `history/`, `adr/`의 `.md` 파일은 맨 위에 이 블록을 둔다.
블록을 빼면 원문 그대로다(옮길 때 깨진 상대 링크의 대상만 고쳤다). 블록을 빼면 원문 그대로다(옮길 때 깨진 상대 링크의 대상만 고쳤다). ADR만은 본문을 한국어로 옮겼다(「문서 수명과 언어」).
```text ```text
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 --> <!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
@@ -118,11 +167,12 @@
- 숫자·버전을 복사하지 않는다. Spring Boot 버전은 `src/gradle/libs.versions.toml`, leaf 목록과 개수는 - 숫자·버전을 복사하지 않는다. Spring Boot 버전은 `src/gradle/libs.versions.toml`, leaf 목록과 개수는
registry(`src/config/architecture/modules.json`)를 가리킨다. registry(`src/config/architecture/modules.json`)를 가리킨다.
- 루트 README는 「프로젝트 구조」(최상위 폴더와 `src/` 폴더가 하는 일)와 「문서 지도」(매뉴얼·계약·운영·결정·기록이 - 루트 README는 「프로젝트 구조」(최상위 폴더와 `src/` 폴더가 하는 일)와 「문서 지도」(매뉴얼·계약·운영·결정·기록이
어디 있나) 절을 반드시 둔다. 전체 절 목록과 순서는 design-docs `conventions/docs-system.md` 6절이다. 어디 있나) 절을 반드시 둔다. 전체 절 목록과 순서의 정본은 design-docs `conventions/docs-system.md` 6.1절이고,
`readme` 검사가 그 목록(`scripts/check-docs.py`의 `README_SECTIONS`)을 본다.
## 문서 검사 ## 문서 검사
`python3 scripts/check-docs.py`가 위 규칙 중 기계로 볼 수 있는 넷을 본다. PR마다 workflow `docs-check`가 `python3 scripts/check-docs.py`가 위 규칙 중 기계로 볼 수 있는 여섯을 본다. PR마다 workflow `docs-check`가
돌리고, 하나라도 걸리면 실패한다. 경로 필터가 없다: 코드에서 파일이나 Gradle 프로젝트를 지우는 변경이 돌리고, 하나라도 걸리면 실패한다. 경로 필터가 없다: 코드에서 파일이나 Gradle 프로젝트를 지우는 변경이
문서를 낡게 만든다. 문서를 낡게 만든다.
@@ -131,14 +181,20 @@
| `language` | 살아 있는 문서와 ADR 본문이 한국어인가(코드·명령·경로·인용은 세지 않는다) | | `language` | 살아 있는 문서와 ADR 본문이 한국어인가(코드·명령·경로·인용은 세지 않는다) |
| `head` | 기록과 ADR 맨 위의 머리 블록: 칸, 상태 어휘, 날짜, 한국어 요약, 현재 정본·대체됨 경로가 있는지 | | `head` | 기록과 ADR 맨 위의 머리 블록: 칸, 상태 어휘, 날짜, 한국어 요약, 현재 정본·대체됨 경로가 있는지 |
| `reference` | 살아 있는 문서의 인라인 코드 안 경로(`src/`, `docs/`, `scripts/`, `compose/`, `.github/`로 시작하는 것과 지운 infra 폴더 아래 경로)와 Gradle 경로가 지금 트리·registry에 있는가. 코드 블록, `> 이력` 인용 블록, 제거 표, `upgrade/`는 보지 않는다 | | `reference` | 살아 있는 문서의 인라인 코드 안 경로(`src/`, `docs/`, `scripts/`, `compose/`, `.github/`로 시작하는 것과 지운 infra 폴더 아래 경로)와 Gradle 경로가 지금 트리·registry에 있는가. 코드 블록, `> 이력` 인용 블록, 제거 표, `upgrade/`는 보지 않는다 |
| `number` | 살아 있는 문서가 Spring Boot 버전이나 leaf 개수를 복사했는가 | | `number` | 살아 있는 문서가 Spring Boot 버전이나 leaf 개수를 복사했는가. Spring Boot 버전은 이름 바로 뒤(「Spring Boot」나 「Boot」 뒤의 세 자리 버전), `Spring Boot` 칸이 있는 표 행의 세 자리 버전, 정본(`src/gradle/libs.versions.toml`의 `springBoot`)과 같은 버전 문자열(굵은 글씨·표 칸·코드 안 포함)을 잡는다. 결정 기록, 제거 표, `upgrade/`는 보지 않는다 |
| `map` | 이 README의 「문서 지도」가 `docs/` 아래 모든 폴더를 덮는가(표 첫 칸의 `폴더/`). 파일 없이 폴더만 가진 묶음 폴더(`history/`)는 그 바로 아래 폴더가 대신한다. 지도에 있지만 없는 폴더도 실패다 |
| `readme` | 루트 README가 첫 줄 제목, 그 아래 한 문단, 정해진 `##` 절을 정해진 순서로 가지는가 |
- 하나만 돌리기: `python3 scripts/check-docs.py --only head`. - 하나만 돌리기: `python3 scripts/check-docs.py --only head`.
- 소스 세트의 resources 폴더 아래 `.md`(`src/**/src/<세트>/resources/`)는 테스트가 읽는 입력이라 문서로 보지 않는다.
- 예외 목록 `scripts/check-docs-exceptions.txt`는 2026-11-07의 기준선이고 줄기만 한다. 문서를 번역하거나 고쳐서 - 예외 목록 `scripts/check-docs-exceptions.txt`는 2026-11-07의 기준선이고 줄기만 한다. 문서를 번역하거나 고쳐서
더는 걸리지 않으면 그 줄을 지운다(남겨 두면 실패한다). 목록에 새 줄을 더하면 실패한다. 기준선을 늘리는 것은 더는 걸리지 않으면 그 줄을 지운다(남겨 두면 실패한다). 목록에 새 줄을 더하면 실패한다. 기준선을 늘리는 것은
규칙을 바꾸는 일이라 소유자 결정이 필요하다. 규칙을 바꾸는 일이라 소유자 결정이 필요하다.
- 줄을 지우면 같은 변경에서 `scripts/check-docs.py`의 `FROZEN`에서 그 줄의 지문도 뺀다. 남겨 두면 실패한다(남은
지문은 지운 줄을 다시 더하는 길이다). 2026-11-07 번역 단계에서 목록과 `FROZEN`이 모두 비었다.
- 검사 자신의 시험: `python3 -m unittest discover -s scripts/tests`. - 검사 자신의 시험: `python3 -m unittest discover -s scripts/tests`.
- 마크다운 상대 링크는 이 검사가 아니라 lychee(`link-check` workflow)와 `scripts/check-work-docs.py --links`가 본다. - 마크다운 링크는 이 검사가 아니라 lychee(`link-check` workflow)와 `scripts/check-work-docs.py --links`가 본다.
기록 안의 외부 링크가 죽어도 기록 본문은 고치지 않는다. 그 URL을 저장소 루트의 `.lycheeignore`에 더한다.
## 여기에 없는 것 ## 여기에 없는 것
@@ -7,122 +7,110 @@
- 현재 정본: `src/build-logic/README.md` - 현재 정본: `src/build-logic/README.md`
<!-- 머리 블록 끝 --> <!-- 머리 블록 끝 -->
# ADR-BUILD-001: `java-test-fixtures` is the standard for shared test code # ADR-BUILD-001: 공유 시험 코드의 표준은 `java-test-fixtures`다
- Status: Accepted - 상태: 채택
- Date: 2026-09-07 - 날짜: 2026-09-07
- Scope: every leaf that publishes or consumes shared test code - 범위: 공유 시험 코드를 내놓거나 쓰는 모든 leaf
- Source: `docs/reviews/2026-09-07-app-bootstrap-module-code-review.md` BOOT-015 - 출처: `docs/reviews/2026-09-07-app-bootstrap-module-code-review.md` BOOT-015
## Context ## 배경
Two conventions do the same job in this repository. 이 저장소에서 같은 일을 하는 규약이 둘 있다.
`ca.testkit-publisher` — a convention plugin — gives a leaf a `testkit` source set, wires its output `ca.testkit-publisher` — 규약 플러그인 — 는 leaf에 `testkit` source set을 주고, 그 출력을 leaf가 이름을 댄 lane에
onto the lanes that leaf names, and optionally publishes it as a consumable configuration. Five 배선하고, 원하면 쓸 수 있는 configuration으로 내놓는다. 다섯 leaf가 쓴다: `persistence-jpa`(`jpaTestkit`으로 내놓음),
leaves use it: `persistence-jpa` (published as `jpaTestkit`), `web` (`webTestkit`), `websocket` `web`(`webTestkit`), `websocket`(`websocketTestkit`), `persistence-mongo`와 `httpclient`(둘 다 내놓지 않음).
(`websocketTestkit`), `persistence-mongo` and `httpclient` (both unpublished).
`java-test-fixtures` — Gradle's own plugin — gives a leaf a `testFixtures` source set, puts it on `java-test-fixtures` — Gradle 자신의 플러그인 — 는 leaf에 `testFixtures` source set을 주고, 그것을 `test`의
`test`'s classpath automatically, and always publishes it as a variant consumers reach with classpath에 자동으로 올리고, 쓰는 쪽이 `testFixtures(project(':x'))`로 닿는 variant로 언제나 내놓는다. 한 leaf가
`testFixtures(project(':x'))`. One leaf uses it: `graphql`, which additionally fails its build when a 쓴다: `graphql`. 이 leaf는 fixture를 `src/testFixtures/java` 밖에 쓰면 빌드를 실패시키기도 한다.
fixture is written outside `src/testFixtures/java`.
Two conventions for one purpose is the defect. A contributor adding shared test code has to know 한 목적에 규약 둘이 있는 것이 결함이다. 공유 시험 코드를 더하는 사람은 파일을 어디 둘지 알기 전에 자기가 어느
which leaf they are in before they know where the file goes, and the two answers are not leaf에 있는지 알아야 하고, 두 답은 서로 바꿔 쓸 수 없다: 첫째를 쓰는 쪽은
interchangeable: a consumer of the first writes `project(path: ':x', configuration: 'jpaTestkit')` `project(path: ':x', configuration: 'jpaTestkit')`를 쓰고 configuration 이름을 알아야 하지만, 둘째를 쓰는 쪽은
and has to know the configuration's name, while a consumer of the second writes `testFixtures(project(':x'))`를 쓰고 그럴 필요가 없다.
`testFixtures(project(':x'))` and does not.
## Decision ## 결정
**`java-test-fixtures` is the standard.** New shared test code goes in `src/testFixtures/java`, and a **`java-test-fixtures`가 표준이다.** 새 공유 시험 코드는 `src/testFixtures/java`에 두고, 쓰는 쪽은
consumer depends on it with `testFixtures(project(':x'))`. `testFixtures(project(':x'))`로 의존한다.
Three reasons, in order of weight: 이유 셋, 무게 순으로:
1. **The consumer side describes itself.** `testFixtures(project(':adapter:inbound:web'))` says what 1. **쓰는 쪽이 스스로를 설명한다.** `testFixtures(project(':adapter:inbound:web'))`는 그것이 무엇인지 말한다.
it is. `project(path: ':adapter:inbound:web', configuration: 'webTestkit')` says where to look, `project(path: ':adapter:inbound:web', configuration: 'webTestkit')`는 어디를 볼지 말하고, 읽는 사람이
and only after the reader has learned that `webTestkit` is a testkit rather than a lane. `webTestkit`이 lane이 아니라 testkit임을 배운 뒤에야 뜻이 통한다.
2. **The enforcement already exists and is copyable.** `graphql`'s build fails when a fixture is 2. **강제 장치가 이미 있고 복사할 수 있다.** `graphql`의 빌드는 fixture를 엉뚱한 곳에 선언하면 실패한다. 같은
declared in the wrong place. The same guard applies unchanged to any leaf that adopts the plugin. guard를 플러그인을 쓰는 어느 leaf에든 바꾸지 않고 적용한다.
3. **It is one fewer local concept.** A convention plugin that reimplements a Gradle plugin has to be 3. **지역 개념이 하나 준다.** Gradle 플러그인을 다시 구현한 규약 플러그인은 그 플러그인에 맞춰 계속 관리해야 한다.
maintained against it.
## What the local plugin does better, and how it is replaced ## 지역 플러그인이 더 잘하는 것과 그것을 대신하는 방법
This is worth writing down, because the review that prompted this ADR recommended the migration 이것은 적어 둘 만하다. 이 ADR을 낳은 리뷰는 `ca.testkit-publisher`를 읽기 전에 옮기기를 권했고, 읽어 보니 그
before reading `ca.testkit-publisher`, and the plugin turns out to encode two deliberate decisions 플러그인은 빠뜨린 것이 아니라 일부러 정한 결정 둘을 담고 있었다.
rather than being an oversight.
**Publishing is opt-in.** `persistence-mongo` and `httpclient` have a testkit and publish nothing; **내놓기는 고를 때만 한다.** `persistence-mongo`와 `httpclient`는 testkit이 있지만 아무것도 내놓지 않는다.
`persistence-jpa` publishes. The plugin's own comment names this as "a real difference in what each `persistence-jpa`는 내놓는다. 플러그인 자신의 주석이 이것을 "a real difference in what each leaf offers rather than
leaf offers rather than an oversight to normalise away". `java-test-fixtures` always creates the an oversight to normalise away"(각 leaf가 주는 것의 실제 차이이지, 맞춰 없앨 빠뜨림이 아니다)라고 부른다.
variant, so the distinction is lost — a leaf that never meant to offer its fixtures will offer them. `java-test-fixtures`는 언제나 variant를 만드니 이 구별이 사라진다 — fixture를 줄 생각이 없던 leaf도 주게 된다.
> Replacement: none at the build level. The distinction moves to review: the fixtures of a leaf that > 대신하는 것: 빌드 수준에서는 없다. 구별은 리뷰로 옮긴다: 아무도 쓰지 않는 leaf의 fixture는 그냥 쓰이지 않는다.
> nobody consumes are simply unconsumed. This is a real, accepted loss. > 실제 손실이고, 받아들인 손실이다.
**Lane consumption is declared.** `persistence-jpa` says `consumedBy 'test', 'postgresqlIntegrationTest'`. **lane이 쓰는 것을 선언한다.** `persistence-jpa`는 `consumedBy 'test', 'postgresqlIntegrationTest'`라고 말한다.
`java-test-fixtures` puts fixtures on `test` only, so every other lane needs the output added `java-test-fixtures`는 fixture를 `test`에만 올리니, 다른 모든 lane에는 출력을 명시해서 더해야 한다.
explicitly.
> Replacement: `strictTestLanes`' existing `compilesAgainst` expresses this unchanged — a lane > 대신하는 것: `strictTestLanes`의 기존 `compilesAgainst`가 바꾸지 않고 이것을 나타낸다 — lane이
> declares `compilesAgainst 'main', 'testFixtures'`. The first draft of this ADR assumed the DSL > `compilesAgainst 'main', 'testFixtures'`를 선언한다. 이 ADR의 첫 초안은 DSL을 바꿔야 한다고 가정했다.
> would need a change, because `sourceSet(name)` creates what it is given and `testFixtures` already > `sourceSet(name)`은 받은 것을 만들고 `testFixtures`는 이미 있기 때문이다. `persistence-mongo`를 옮겨 보니 아니었다:
> exists. The `persistence-mongo` migration showed otherwise: `compilesAgainst` only *looks a source > `compilesAgainst`는 source set을 *찾기만* 하므로, 플러그인이 만든 것의 이름을 대도 그대로 된다. leaf가 버리는 것은
> set up*, so naming a plugin-created one works as-is. What the leaf drops is the > lane의 선언이 아니라 `sourceSet('testkit')` 선언이다.
> `sourceSet('testkit')` declaration, not the lane's.
## Migration: done, and what it cost ## 옮기기: 끝났고, 든 비용
Five leaves, eleven lanes, two published testkits, all migrated leaf by leaf with the suite run leaf 다섯, lane 열하나, 내놓은 testkit 둘을 leaf 하나씩, 그 사이마다 suite를 돌리며 모두 옮겼다.
between each. `ca.testkit-publisher` is deleted. `ca.testkit-publisher`는 지웠다.
The order was chosen so a mistake would be cheap: unpublished leaves first, published ones last with 순서는 실수가 싸게 끝나도록 골랐다: 내놓지 않는 leaf를 먼저, 내놓는 leaf를 마지막에 그 쓰는 쪽과 같은 단계에서.
their consumer in the same step.
1. `persistence-mongo` — one leaf, two lanes, no cross-module consumer; the proof the path works. 1. `persistence-mongo` — leaf 하나, lane 둘, 다른 모듈의 쓰는 쪽 없음. 길이 되는지 보는 증명이다.
What it took, per leaf: leaf마다 든 일:
- `apply plugin: 'java-test-fixtures'` at the top of the leaf build file; - leaf 빌드 파일 맨 위에 `apply plugin: 'java-test-fixtures'`;
- `git mv src/testkit src/testFixtures`; - `git mv src/testkit src/testFixtures`;
- drop `sourceSet('testkit')` and the whole `testkitPublisher` block; keep every other lane's - `sourceSet('testkit')`와 `testkitPublisher` 블록 전체를 버린다. 다른 모든 lane의 `compilesAgainst`는 두고
`compilesAgainst`, renaming `'testkit'` to `'testFixtures'`; `'testkit'`을 `'testFixtures'`로 이름을 바꾼다;
- rename `testkitImplementation` to `testFixturesImplementation`, **and add what the old source - `testkitImplementation`을 `testFixturesImplementation`으로 이름을 바꾸고, **옛 source set이 소리 없이
set was inheriting silently**. This is the one non-mechanical step: `testkit*` extended 물려받던 것을 더한다**. 기계적이지 않은 단계는 이것 하나다: `testkit*`는 `testImplementation`을 상속해서,
`testImplementation`, so the fixtures saw every test library the leaf declared. Mongo's needed fixture가 leaf가 선언한 모든 시험 라이브러리를 봤다. Mongo는 네 줄(AssertJ, BSON, Spring Data commons,
four more lines (AssertJ, BSON, Spring Data commons, Toxiproxy) — none of which the leaf had Toxiproxy)이 더 필요했다 — leaf가 fixture의 의존으로 적은 적이 한 번도 없는 것들이다;
ever stated the fixtures depended on; - leaf의 잠금 상태를 다시 만든다.
- regenerate the leaf's lock state. 2. `httpclient`, 그다음 `websocket` — 역시 내놓지 않고, lane이 더 많다.
2. `httpclient`, then `websocket` — unpublished as well, more lanes. 3. `web`과 `persistence-jpa`, 그리고 `app-bootstrap`의 쓰는 쪽 선언 둘. 그 선언은
3. `web` and `persistence-jpa` with `app-bootstrap`'s two consumer declarations, which became `testImplementation(testFixtures(project(':…')))`가 됐다.
`testImplementation(testFixtures(project(':…')))`. 4. `ca.testkit-publisher`를 지웠다. 그 `plugins {}` 항목과 루트 빌드의 적용도 함께.
4. `ca.testkit-publisher` deleted, along with its `plugins {}` entry and its application in the root
build.
### Two things the migration broke, and what they taught ### 옮기기가 깨뜨린 것 둘과 그것이 가르친 것
Both were caught by tests that exist to catch exactly this, which is the argument for having them. 둘 다 바로 이것을 잡으려고 있는 시험이 잡았다. 그런 시험을 둘 이유가 그것이다.
**ArchUnit corpora went wrong in opposite directions.** `httpclient`'s boundary rules *excluded* **ArchUnit 대상 묶음이 반대 방향으로 틀어졌다.** `httpclient`의 경계 규칙은 `build/classes/java/testkit`을
`build/classes/java/testkit`; after the move the fixtures arrived as a `…-test-fixtures.jar` on the *뺐다*. 옮긴 뒤 fixture는 같은 classpath에 `…-test-fixtures.jar`로 들어왔고, 그래서 빼기가 그것을 놓쳤으며
same classpath, so the exclusion missed them and 258 fixture-to-fixture calls were reported as fixture 사이 호출 258개가 운영 코드가 testkit에 의존한다고 보고됐다. `persistence-jpa`의 규칙은
production depending on the testkit. `persistence-jpa`'s rules *included* only `build/classes/java/main`만 *넣었다*. `java-test-fixtures`를 적용하면 모듈 자신의 시험 classpath가 모듈을 class
`build/classes/java/main`; applying `java-test-fixtures` makes the module's own test classpath carry 디렉터리가 아니라 **jar**로 싣는다. 그래서 대상 묶음이 비었다. 위험한 쪽은 둘째다 — 빈 묶음이면 모든
the module as a **jar** rather than as a class directory, so its corpus became empty. The second is `noClasses()` 규칙이 통과한다 — 그리고 그 suite가 무엇이든 단언하기 전에 묶음이 비어 있지 않음을 단언했기
the dangerous one — an empty corpus makes every `noClasses()` rule pass — and it surfaced only 때문에만 드러났다.
because that suite asserts its corpus is non-empty before asserting anything about it.
**Fixtures had invisible dependencies.** `testkit*` configurations extended `testImplementation`, so **fixture에 보이지 않는 의존이 있었다.** `testkit*` configuration은 `testImplementation`을 상속해서, fixture는 이름
the fixtures compiled against every test library their leaf declared without ever naming one. Making 한 번 대지 않고 leaf가 선언한 모든 시험 라이브러리에 대고 컴파일됐다. 그것을 명시하는 데 다섯 leaf에 걸쳐
them explicit took roughly thirty `testFixturesImplementation` lines across the five leaves — `testFixturesImplementation` 줄이 대략 서른 개 들었다 — Micrometer, Spring Web, Netty, logback, Jackson, JUnit, AssertJ,
Micrometer, Spring Web, Netty, logback, Jackson, JUnit, AssertJ, Spring Data. None of them were Spring Data. 틀린 것은 없었다. 적힌 것도 없었다.
wrong; none of them were stated.
## Consequences ## 결과
- `docs/testing/TESTING_STRATEGY.md` §5 records the standard; this ADR records why and at what cost. - `docs/testing/TESTING_STRATEGY.md` §5가 표준을 적는다. 이 ADR은 왜, 어떤 비용으로인지를 적는다.
- Until step 5, two conventions remain visible. The strategy document says so explicitly, so a - 5단계까지는 규약 둘이 보이는 채로 남는다. 전략 문서가 그것을 분명히 말하므로, 읽는 사람이 어느 것이 지금
contributor reading it is not left to infer which one is current. 것인지 짐작하게 두지 않는다.
- The opt-in-publishing distinction is given up. If it later proves load-bearing — a leaf whose - 고를 때만 내놓는 구별은 포기한다. 나중에 그것이 꼭 필요한 것으로 드러나면 — fixture에 정말 닿으면 안 되는
fixtures genuinely must not be reachable — the answer is a separate module, not a third convention. leaf — 답은 세 번째 규약이 아니라 따로 둔 모듈이다.
@@ -7,73 +7,63 @@
- 현재 정본: `src/adapter/inbound/graphql/README.md` - 현재 정본: `src/adapter/inbound/graphql/README.md`
<!-- 머리 블록 끝 --> <!-- 머리 블록 끝 -->
# ADR-GQL-001 — GraphQL context stays inbound; object authorization moves to application-core; the persisted-operation store stays an inbound SPI # ADR-GQL-001 — GraphQL 문맥은 inbound에 머물고, 객체 인가는 application-core로 옮기며, persisted operation 저장소는 inbound SPI로 남는다
- Status: Accepted - 상태: 채택
- Date: 2026-08-24 - 날짜: 2026-08-24
- Review: `docs/reviews/2026-08-14-graphql-module-code-review.md` GQL-026 - 리뷰: `docs/reviews/2026-08-14-graphql-module-code-review.md` GQL-026
## Context ## 배경
The GraphQL leaf's own documentation described three things crossing its boundary: a GraphQL leaf 자신의 문서는 경계를 넘는 것 셋을 적었다: application, JPA, Mongo, HTTP client로 deadline을 전파하는
`GraphQlRequestContext` with a deadline propagated into application, JPA, Mongo and the HTTP client; `GraphQlRequestContext`, 전송 계층 안에서 정하는 객체 인가, 외부 durable 저장소가 구현하는 persisted operation
object authorization decided inside the transport; and a persisted-operation registry implemented by registry.
an external durable store.
Two of those invert the dependency direction. If `application-core` or an outbound adapter 그중 둘은 의존 방향을 뒤집는다. `application-core`나 outbound 어댑터가 `adapter:inbound:graphql`에 있는 타입을
implements a type that lives in `adapter:inbound:graphql`, the registry edge that says inbound 구현하면, inbound가 application에 의존한다는 registry edge는 만족되지만 실제 컴파일 의존은 반대로 간다.
depends on application is satisfied while the real compile-time dependency runs the other way.
The third is a business rule in the wrong layer: whether an actor may see an object is a decision 셋째는 엉뚱한 계층의 업무 규칙이다: actor가 객체를 볼 수 있는지는 도메인에 대한 판단이고, GraphQL은 이 골격이
about the domain, and GraphQL is one of four transports this skeleton ships. 싣는 전송 계층 넷 중 하나다.
## Decision ## 결정
Three different answers, because the three problems are not the same problem. 세 문제가 같은 문제가 아니므로 답도 셋이다.
**GraphQL context stays inbound-local.** It is mapped explicitly onto application command fields — **GraphQL 문맥은 inbound 안에 머문다.** 타입으로 실려 다니지 않고 application command 필드 — actor, tenant,
actor, tenant, deadline — rather than travelling as a type. Nothing outside the leaf references deadline — 로 명시해 대응시킨다. leaf 밖의 어떤 것도 `GraphQlRequestContext`를 참조하지 않고, 경계 시험은 leaf
`GraphQlRequestContext`, and the boundary test is that grep returns nothing outside it. 밖에서 grep이 아무것도 돌려주지 않는 것이다.
**Object authorization moves to `application-core`.** `ObjectAccessPolicy`, `ObjectAccessRequest` **객체 인가는 `application-core`로 옮긴다.** `ObjectAccessPolicy`, `ObjectAccessRequest`, `ObjectAccessDecision`은
and `ObjectAccessDecision` are transport-neutral and live with the other application policies; 전송 중립이고 다른 애플리케이션 정책과 함께 있다. GraphQL leaf의 `ApplicationObjectAuthorization`이 그것을 부르는
`ApplicationObjectAuthorization` in the GraphQL leaf is the bridge that calls them. This is the one 다리다. 셋 중 이것이 실제 계층 결함이었고, 적어 두지 않고 고친다.
of the three that was a real layering defect, and it is fixed rather than documented.
**The persisted-operation store stays an inbound-owned SPI.** `GraphQlPersistedOperationRegistry` **persisted operation 저장소는 inbound가 가진 SPI로 남는다.** `GraphQlPersistedOperationRegistry`는
remains in `advanced/persisted`, and no leaf outside GraphQL implements it. `advanced/persisted`에 남고, GraphQL 밖의 어떤 leaf도 그것을 구현하지 않는다.
## Consequences ## 결과
The third decision is the one that needs defending, because it leaves the reported risk in place 변호가 필요한 것은 셋째 결정이다. 보고된 위험을 없애지 않고 그 자리에 두기 때문이다.
rather than removing it.
The risk is conditional: the direction inverts only when something outside the leaf implements the 위험은 조건부다: leaf 밖의 무엇이 그 인터페이스를 구현할 때만 방향이 뒤집힌다. 그런 것은 없다. 템플릿은 메모리
interface. Nothing does. The template ships an in-memory registry and no durable one, because it registry를 싣고 durable registry는 싣지 않는다. persisted operation 저장소를 아예 싣지 않기 때문이다.
ships no persisted-operation store at all.
The alternative was to introduce a generic operational key-value store port owned by a neutral 대안은 중립 계약 보유자가 가진 범용 운영 key-value 저장소 포트를 들이고, GraphQL 어댑터는 키와 값 대응만 가지는
contract holder, with the GraphQL adapter owning only the key and value mapping. That port would 것이었다. 그 포트는 인터페이스 정확히 하나, 구현 0개, 짐작으로 정한 쓰는 쪽 하나를 가졌을 것이다 — 아무도 말하지
have exactly one interface, zero implementations and one speculative consumer — a new abstraction 않은 요구에서 모양을 짐작한 새 추상이다. 이 저장소는 있었지만 아무것도 닿지 않던 통제를 지우는 데 수정 한 바퀴를
whose shape is guessed from a requirement nobody has stated. This repository has spent a full 통째로 썼다. 없는 저장소를 위해 포트를 지어내는 것이 그런 것을 다음에 또 쓰는 길이다.
remediation pass deleting controls that existed and were reached by nothing, and inventing a port
for a store that does not exist is how the next one of those gets written.
So the decision is to leave the SPI where it is and to move it when a durable store is actually 그래서 결정은 SPI를 있는 곳에 두고, durable 저장소를 실제로 만들 때 옮기는 것이다. 그때 옮기는 일은 leaf 하나와
built. Moving it then is a rename across one leaf and one new adapter, which is cheaper than 새 어댑터 하나에 걸친 이름 바꾸기이고, 그때까지 틀린 추상을 끌고 다니는 것보다 싸다. 그동안 일어나면 안 되는 것은
carrying a wrong abstraction until then. What must not happen in the meantime is an outbound leaf outbound leaf가 inbound 인터페이스를 구현하는 것이다. 그때가 방향이 실제로 뒤집히는 순간이고, 그것은 계층 변경이
implementing the inbound interface, because that is the moment the direction actually inverts, and 아니라 구현처럼 보이는 diff의 커밋에서 일어날 것이다.
it would happen in a commit whose diff looks like an implementation rather than a layering change.
The composition root wires these and owns no business or storage policy of its own. 조립 루트가 이것들을 배선하고, 자기 업무·저장 정책은 가지지 않는다.
## Enforcement ## 강제
`verifyCleanArchitectureDependencies` and `modules.json` hold the leaf's edges to `verifyCleanArchitectureDependencies`와 `modules.json`이 leaf의 `domain-core`, `application-core`, `shared-contract`
`domain-core`, `application-core` and `shared-contract`. `ObjectAccessPolicyTest` covers the edge를 지킨다. `ObjectAccessPolicyTest`가 application 쪽 정책을, `ApplicationObjectAuthorizationTest`가 다리를 덮는다.
application-side policy and `ApplicationObjectAuthorizationTest` the bridge.
The condition this ADR turns on — that nothing outside the GraphQL leaf implements the 이 ADR이 기대는 조건 — GraphQL leaf 밖의 어떤 것도 persisted operation SPI를 구현하지 않는다 — 은 저장소 전체에
persisted-operation SPI — is a claim about the whole repository, so it is checked at the 대한 주장이다. 그래서 leaf 안이 아니라 조립 루트에서, `app-bootstrap` architecture suite의 다른 GraphQL 경계 규칙
composition root rather than inside the leaf, next to the other GraphQL boundary rules in 옆에서 검사한다.
`app-bootstrap`'s architecture suite.
@@ -7,58 +7,51 @@
- 현재 정본: `docs/compatibility/grpc-support-matrix.md` - 현재 정본: `docs/compatibility/grpc-support-matrix.md`
<!-- 머리 블록 끝 --> <!-- 머리 블록 끝 -->
# ADR-GRPC-001: The gRPC platform ships as a registered family, not as one adapter leaf # ADR-GRPC-001: gRPC 플랫폼은 adapter leaf 하나가 아니라 등록된 family로 싣는다
- Status: accepted - 상태: 채택
- Date: 2026-08-30 - 날짜: 2026-08-30
- Scope: `:grpc:*`, `:grpc-advanced:*`, `src/config/architecture/modules.json` - 범위: `:grpc:*`, `:grpc-advanced:*`, `src/config/architecture/modules.json`
## Context ## 배경
The two source plans describe a type-safe gRPC execution platform with its own API, SPI, adapters and 두 원본 계획은 자기 API, SPI, 어댑터, 조립 루트를 가진 타입 안전 gRPC 실행 플랫폼을 설명한다: `modules/grpc` 아래
composition root: fifteen Stable modules under `modules/grpc` and sixteen Advanced ones under Stable 모듈 열다섯과 `modules/grpc-advanced` 아래 Advanced 모듈 열여섯, Gradle Kotlin DSL, 패키지
`modules/grpc-advanced`, on Gradle Kotlin DSL, in package `io.backend.skeleton.grpc`, against `io.backend.skeleton.grpc`, Spring Boot 4.1 기준.
Spring Boot 4.1.
None of that layout exists here. This repository uses Groovy DSL, a fail-closed module registry that 그 배치는 여기 하나도 없다. 이 저장소는 Groovy DSL, leaf 목록을 가진 실패하면 닫히는 모듈 registry, 패키지 루트
owns the leaf list, package root `dev.caskeleton`, and Spring Boot 4.0.8. The plans anticipate this: `dev.caskeleton`, Spring Boot 4.0.8을 쓴다. 계획은 이것을 예상한다: 마지막 Global Constraint가, 저장소 구조가 다르면
their last Global Constraint says that when the repository structure differs, file paths are remapped 파일 경로를 다시 대응시키고 공개 계약·불변식·시험의 뜻은 바꾸지 않는다고 말한다.
and the public contracts, invariants and test meanings are not changed.
Two shapes were available. Fold the platform into the existing `:adapter:inbound:grpc` leaf as 고를 수 있는 모양은 둘이었다. 플랫폼을 기존 `:adapter:inbound:grpc` leaf에 패키지로 접어 넣기 — JPA, GraphQL,
packages — which is what the JPA, GraphQL, WebSocket and HTTP platforms did here — or register it as WebSocket, HTTP 플랫폼이 여기서 그렇게 했다 — 또는 `messaging:*`를 등록한 방식대로 family로 등록하기.
a family the way `messaging:*` is registered.
## Decision ## 결정
Register it as a family: twelve Stable leaves under `src/grpc/` and six Advanced ones under family로 등록한다: `src/grpc/` 아래 Stable leaf 열둘과 `src/grpc-advanced/` 아래 Advanced leaf 여섯.
`src/grpc-advanced/`.
The deciding property is that this is not a layer of this application. Root `CLAUDE.md` already 결정을 가른 성질은 이것이 이 애플리케이션의 계층이 아니라는 점이다. 루트 `CLAUDE.md`는 이미 `messaging:*`를 "a
describes `messaging:*` as "a vendored messaging platform: a product with its own API, SPI, adapters vendored messaging platform: a product with its own API, SPI, adapters and composition boundary, not a layer of this
and composition boundary, not a layer of this application", and the gRPC platform is the same shape application"(들여온 메시징 플랫폼: 자기 API, SPI, 어댑터, 조립 경계를 가진 제품이고 이 애플리케이션의 계층이
for the same reason — the application is meant to reach it the way it reaches a library, through an 아니다)이라고 설명하고, gRPC 플랫폼은 같은 이유로 같은 모양이다 — 애플리케이션은 라이브러리에 닿듯, 애플리케이션이
application-owned port. The four platforms that became packages are all layers of this application; 가진 포트를 거쳐 그것에 닿아야 한다. 패키지가 된 네 플랫폼은 모두 이 애플리케이션의 계층이다. 이것은 아니다.
this one is not.
The split between `src/grpc/` and `src/grpc-advanced/` is not organisational. The Stable plan `src/grpc/`와 `src/grpc-advanced/`의 분리는 정리용이 아니다. Stable 계획은 Stable starter의 빌드가 Advanced 모듈에
requires that the Stable starter's build fail if it reaches an Advanced module, and separate Gradle 닿으면 실패해야 한다고 요구하고, Gradle 경로 접두어를 따로 두면 그것이 리뷰 메모가 아니라
path prefixes make that a `verifyCleanArchitectureDependencies` failure rather than a review note: `verifyCleanArchitectureDependencies` 실패가 된다: `grpc-spring-boot-starter`의 registry 항목은 advanced id를 하나도
`grpc-spring-boot-starter`'s registry entry names no advanced id, and it cannot acquire one silently. 대지 않고, 소리 없이 얻을 수도 없다.
## Consequences ## 결과
**The registry grew from 44 leaves to 62.** That is a large registry change, made deliberately and in **registry가 leaf 44개에서 62개로 늘었다.** 큰 registry 변경이고, 일부러 한곳에서 했다. 새 leaf는 모두
one place. Every new leaf is `runtime_memberships: []`, so nothing ships until a second, explicit `runtime_memberships: []`라서, 두 번째로 명시한 결정이 옮기기 전까지 아무것도 실리지 않는다.
decision moves it.
**The advanced boundary is checked twice.** Once by the registry at build time, and once by **advanced 경계는 두 번 검사한다.** 빌드 때 registry가 한 번, 런타임에 `GrpcStableBuildInvariant`가 한 번. fat jar나
`GrpcStableBuildInvariant` at runtime, because a fat jar or a shaded artifact is assembled by shaded artifact는 registry가 보지 못하는 무언가가 조립하기 때문이다.
something the registry never sees.
**Four testkit modules became four test lanes.** The plan's split exists so in-process results cannot **testkit 모듈 넷은 시험 lane 넷이 됐다.** 계획이 나눈 이유는 프로세스 안 결과를 네트워크 결과로 착각하지 못하게
be mistaken for network results; this repository expresses that with `ca.strict-test-lane`, whose 하려는 것이다. 이 저장소는 그것을 `ca.strict-test-lane`으로 나타낸다. 그 lane은 아무것도 찾지 못하면 실패하고,
lanes fail when they discover nothing and never serve an up-to-date result. `GrpcEvidenceGrade` keeps up-to-date 결과를 내주지 않는다. `GrpcEvidenceGrade`가 코드 안에서 같은 규칙을 지키므로, 보고서가 계약 실행을 전송
the same rule inside the code, so a report cannot cite a contract run as transport evidence. 증거로 인용할 수 없다.
**Codegen is not wired.** See ADR-GRPC-002. **codegen은 배선하지 않았다.** ADR-GRPC-002를 본다.
@@ -8,74 +8,65 @@
- 대체됨: `docs/capability-status.md` - 대체됨: `docs/capability-status.md`
<!-- 머리 블록 끝 --> <!-- 머리 블록 끝 -->
# ADR-GRPC-002: Schema governance runs without protoc and without the Buf CLI # ADR-GRPC-002: schema 관리는 protoc 없이, Buf CLI 없이 돈다
- Status: **superseded (2026-09-28)** by owner decision 18 of the 2026-09-25 review follow-up - 상태: **대체됨(2026-09-28)** — 2026-09-25 리뷰 후속의 소유자 결정 18
- Date: 2026-08-30 - 날짜: 2026-08-30
- Scope: `:grpc:grpc-proto-contract`, `:grpc:grpc-codegen` (both removed) - 범위: `:grpc:grpc-proto-contract`, `:grpc:grpc-codegen`(둘 다 지움)
> **Superseded.** The regex `.proto` validator and the Java re-implementation of Buf's rules were > **대체됨.** 정규식 `.proto` 검증기와 Buf 규칙의 Java 재구현은 지웠다. schema는 이제 `:grpc:grpc-contract`
> deleted. The schema now lives in `:grpc:grpc-contract` (`src/grpc/grpc-contract/src/main/proto`), > (`src/grpc/grpc-contract/src/main/proto`)에 있고 Gradle protobuf 플러그인(`com.google.protobuf`, 버전은
> compiled by the Gradle protobuf plugin (`com.google.protobuf`, version pinned in > `src/gradle/libs.versions.toml`에 고정. protoc와 protobuf-java runtime은 둘 다 `protobufGrpc`)이 컴파일한다. 생성된
> `src/gradle/libs.versions.toml`; protoc and the protobuf-java runtime are both `protobufGrpc`). > 소스는 그 leaf에서만 Spotless, Checkstyle, Error Prone에서 뺀다. `buf lint`와 `buf breaking`
> Generated sources are excluded from Spotless, Checkstyle and Error Prone in that leaf only. > (`src/grpc/grpc-contract/buf.yaml`, STANDARD lint, FILE breaking)은 CI의 `.github/workflows/ci-quality-gates.yml`
> `buf lint` and `buf breaking` (`src/grpc/grpc-contract/buf.yaml`, STANDARD lint, FILE breaking) > job `grpc-proto-buf`에서 돈다. proto organization은 `caskeleton`이다(예전에는 `hyeonworks`). 아래 글은 원래 결정의
> run in CI, job `grpc-proto-buf` in `.github/workflows/ci-quality-gates.yml`. The proto organization > 기록으로 남긴다.
> is `caskeleton` (was `hyeonworks`). The text below is kept as the record of the original decision.
## Context ## 배경
Stable Tasks 8 through 11 require proto style rules, Buf format/lint/breaking governance, a single Stable Task 8부터 11은 proto 문체 규칙, Buf format·lint·breaking 관리, Java codegen 소유자 하나, 그리고 쓰는 쪽
Java codegen owner, and a descriptor artifact whose consumer-compile result gates a release. 컴파일 결과가 릴리스를 막는 descriptor artifact를 요구한다.
Two of the tools those tasks name are absent from this toolchain. The Buf CLI is not installed. And 그 Task가 이름을 대는 도구 중 둘이 이 toolchain에 없다. Buf CLI는 설치돼 있지 않다. 그리고 `protoc`는 Gradle
`protoc` is available through the Gradle protobuf plugin, but every leaf in this repository passes protobuf 플러그인으로 쓸 수 있지만, 이 저장소의 모든 leaf는 google-java-format을 쓴 spotless, checkstyle, HIGH
spotless with google-java-format, checkstyle, SpotBugs at HIGH confidence, Error Prone and `-Werror` confidence의 SpotBugs, Error Prone, `-Werror`를 통과하는데 — 생성된 protobuf 소스는 그중 어느 것도 통과하지 못한다.
— and generated protobuf sources pass none of them. Turning codegen on means excluding a source set codegen을 켜면 source set 하나를 품질 게이트 다섯에서 빼야 한다.
from five quality gates.
There is precedent for such an exclusion: the `jmh` source set has `spotbugsJmh` and `checkstyleJmh` 그런 예외에는 선례가 있다: `jmh` source set은 `spotbugsJmh`와 `checkstyleJmh`를 끄고 Error Prone도 끈다. 그러니 빼는
disabled and Error Prone off. So the carve-out is available. It is also a decision about the quality 길은 있다. 하지만 그것은 Task 하나를 위해 leaf의 품질 기준선에 대해 내리는 결정이고, 이 일이 바꾸라고 받은 범위
baseline of a leaf, taken for one task, and outside what this work was asked to change. 밖이다.
`adapter:inbound:grpc` also carries a recorded decision in the opposite direction: its `CLAUDE.md` `adapter:inbound:grpc`에도 반대 방향으로 기록된 결정이 있다: 그 `CLAUDE.md`는 쓰는 기능 모듈이 자기 schema를 가져야
forbids the protobuf plugin and `.proto` in that leaf, on the grounds that a consuming feature module 한다는 이유로 그 leaf에서 protobuf 플러그인과 `.proto`를 금지한다.
should own its schema.
## Decision ## 결정
Commit the `.proto` sources and implement every rule the tasks require as executable Java, with no `.proto` 소스를 커밋하고, Task가 요구하는 모든 규칙을 protoc 실행도 Buf CLI 호출도 없이 실행되는 Java로 구현한다.
protoc run and no Buf CLI invocation.
`GrpcProtoContractValidator` reads `.proto` text and enforces proto3 syntax, the `GrpcProtoContractValidator`는 `.proto` 글을 읽고 다음을 강제한다: proto3 문법, `{organization}.{domain}.v{major}`
`{organization}.{domain}.v{major}` package rule, `java_multiple_files`, a generated Java package 패키지 규칙, `java_multiple_files`, 손으로 쓴 것과 겹치지 않는 생성 Java 패키지, `_UNSPECIFIED` enum 0값, 받은 삭제
disjoint from the hand-written one, `_UNSPECIFIED` enum zero values, `reserved` declarations checked 이력과 대조한 `reserved` 선언, well-known type 허용 목록, map 필드 허용 목록. 자기 시험에서 커밋한 schema에 대고
against a supplied removal history, a well-known-type allowlist and a map-field allowlist. It runs 돌므로, 출하하는 `.proto` 파일은 장식이 아니라 살아 있다.
against the committed schema in its own test, so the shipped `.proto` files are live rather than
decorative.
`GrpcBufPolicy` fixes the breaking gate at Buf's `FILE` category and names the four lifecycle stages `GrpcBufPolicy`는 breaking gate를 Buf의 `FILE` category로 고정하고, 규칙을 따르는 pipeline이 등록하는 lifecycle 단계
a compliant pipeline registers. `GrpcCodegenManifest` fixes one codegen owner and refuses a literal 넷을 이름으로 댄다. `GrpcCodegenManifest`는 codegen 소유자를 하나로 고정하고 리터럴 생성기 버전을 거절한다.
generator version. `GrpcDescriptorArtifact`, `GrpcConsumerFixture` and `GrpcSchemaArtifactPublisher` `GrpcDescriptorArtifact`, `GrpcConsumerFixture`, `GrpcSchemaArtifactPublisher`는 schema hash, descriptor digest, 쓰는
carry the schema hash, the descriptor digest and the per-consumer source-break report, and refuse a 쪽별 소스 깨짐 보고를 싣고, 쓰는 쪽을 깨뜨리는 게시나 이미 릴리스한 버전을 다른 바이트로 다시 게시하는 것을
publish that breaks a consumer or republishes a released version with different bytes. 거절한다.
The committed `buf.yaml` states the same rules, so running the CLI in an environment that has it 커밋한 `buf.yaml`도 같은 규칙을 적으므로, CLI가 있는 환경에서 돌리면 같은 판정에 닿는다.
reaches the same verdict.
## Consequences ## 결과
**The invariants are enforced; the process is not run.** Everything Tasks 8 to 11 are about — which **불변식은 강제하고, 과정은 돌리지 않는다.** Task 8부터 11이 다루는 모든 것 — 어떤 schema 변경을 거절하는지, 어떤
schema changes are refused, which consumer breaks block a release, who owns generation — is a 쓰는 쪽 깨짐이 릴리스를 막는지, 생성을 누가 가지는지 — 이 여기서는 빌드로 검사하는 규칙이다. 빠진 것은 protoc
build-checkable rule here. What is missing is the protoc invocation and the Buf binary. 호출과 Buf 바이너리다.
**Turning codegen on is a bounded change.** `GrpcCodegenManifest.caSkeleton()` already names the **codegen을 켜는 것은 한계 있는 변경이다.** `GrpcCodegenManifest.caSkeleton()`이 이미 실제 플러그인 설정이 만족해야
owner, the managed version source, the build-directory output paths and the disjoint package policy 할 소유자, 관리되는 버전 출처, 빌드 디렉터리 출력 경로, 겹치지 않는 패키지 정책을 이름으로 댄다. 할 일은 source set
that a real plugin configuration has to satisfy. The work is a source-set carve-out and a plugin 예외와 플러그인 블록이지 재설계가 아니다.
block, not a redesign.
**The fixtures use a text codec.** `GrpcTextCodec` gives the testkit a UTF-8 marshaller so the **fixture는 텍스트 codec을 쓴다.** `GrpcTextCodec`이 testkit에 UTF-8 marshaller를 줘서, 프로세스 안 lane과 Netty
in-process and Netty lanes can exercise interceptors, status mapping, metadata limits and stream lane이 생성된 stub 없이 interceptor, status 대응, metadata 한계, stream 순서를 시험할 수 있다. 그 계약은 메시지
sequencing without generated stubs. Those contracts are properties of the platform and the transport, 모양이 아니라 플랫폼과 전송의 성질이므로 바꿔 넣어도 잃는 것이 없다 — 그리고 lane이 codegen이 들어온 뒤가 아니라
not of any message shape, so the substitution costs nothing — and the lanes run today rather than 오늘 돈다.
after codegen lands.
@@ -7,53 +7,48 @@
- 현재 정본: `docs/compatibility/grpc-support-matrix.md` - 현재 정본: `docs/compatibility/grpc-support-matrix.md`
<!-- 머리 블록 끝 --> <!-- 머리 블록 끝 -->
# ADR-GRPC-003: Transport, business and stream evidence are three axes, and none implies another # ADR-GRPC-003: 전송·업무·stream 증거는 세 축이고, 어느 것도 다른 것을 뜻하지 않는다
- Status: accepted - 상태: 채택
- Date: 2026-08-30 - 날짜: 2026-08-30
- Scope: `:grpc:grpc-core-api`, `:grpc:grpc-runtime` (was `grpc-policy`), `:grpc:grpc-testkit` - 범위: `:grpc:grpc-core-api`, `:grpc:grpc-runtime`(예전 `grpc-policy`), `:grpc:grpc-testkit`
## Context ## 배경
A failed RPC produces a status code, and a status code is not an answer to the question the caller 실패한 RPC는 status code를 낸다. 그리고 status code는 호출자가 실제로 가진 질문의 답이 아니다. 변경 요청의
actually has. `DEADLINE_EXCEEDED` on a mutation does not say whether the mutation happened; `DEADLINE_EXCEEDED`는 변경이 일어났는지 말하지 않는다. 요청을 보낸 뒤의 `UNAVAILABLE`은 서버가 그것을 한 번도 보지
`UNAVAILABLE` after the request was sent does not say the server never saw it; response headers 않았다고 말하지 않는다. 응답 header가 도착했다고 트랜잭션이 커밋된 것은 아니다.
arriving does not say a transaction committed.
Every one of those is a place where a plausible inference produces a duplicate write or a lost one, 그 하나하나가 그럴듯한 추론이 중복 쓰기나 잃은 쓰기를 낳는 자리이고, 성공 경로만 시험하는 시험에서는 하나도 보이지
and none of them is visible in a test that only exercises the happy path. 않는다.
## Decision ## 결정
Model what happened as three independent axes, and refuse the inferences between them. 일어난 일을 서로 독립인 세 축으로 모델링하고, 축 사이의 추론을 거절한다.
`GrpcTransportEvidence` records what the client observed on the wire, and distinguishes `NOT_SENT` — `GrpcTransportEvidence`는 client가 wire에서 본 것을 기록하고, `NOT_SENT` — client가 자기 보내기가 실패하는 것을 봤다
the client watched its own send fail — from `UNOBSERVED`, which is every other case where nothing is — 와, 아무것도 모르는 다른 모든 경우인 `UNOBSERVED`를 구별한다. `GrpcBusinessEvidence`는 애플리케이션이 확인한 것을
known. `GrpcBusinessEvidence` records what the application confirmed, with `COMMIT_UNKNOWN` as a real 기록하고, `COMMIT_UNKNOWN`은 자리표시가 아니라 실제 상태다. `GrpcStreamEvidence`는 sealed 계층이고, 비어 있지 않은
state rather than a placeholder. `GrpcStreamEvidence` is a sealed hierarchy whose non-empty cases all 경우는 모두 위치를 싣는다. 마지막 순번 없는 「부분」은 이어 가지도 맞춰 보지도 못하기 때문이다.
carry a position, because "partial" without a last sequence can be neither resumed nor reconciled.
`GrpcExecutionEvidence` holds all three and rejects combinations nobody could have observed: a unary `GrpcExecutionEvidence`는 셋을 모두 가지고, 아무도 볼 수 없었을 조합을 거절한다: stream 증거가 있는 unary 호출, 또는
call with stream evidence, or a request the client watched fail to send that nonetheless carries client가 보내기 실패를 봤는데도 업무 증거를 실은 요청. 응답 header를 확인된 커밋으로 올리는 것은
business evidence. Promoting response headers to a confirmed commit is possible only by editing `withResponseHeadersSeen`을 고쳐야만 할 수 있다. 그것은 interceptor 안의 그럴듯한 한 줄이 아니라 메서드 하나다.
`withResponseHeadersSeen`, which is one method rather than a plausible line in an interceptor.
`GrpcCompletionOutcome.forMutation` derives what a caller may conclude, and defaults `GrpcCompletionOutcome.forMutation`이 호출자가 결론 내릴 수 있는 것을 끌어내고, 변경 요청의 `DEADLINE_EXCEEDED`와
`DEADLINE_EXCEEDED` and post-send `UNAVAILABLE` on a mutation to `COMPLETION_UNKNOWN`. 보낸 뒤의 `UNAVAILABLE`을 기본으로 `COMPLETION_UNKNOWN`으로 둔다.
The same types are used by the failure model and by the observation convention, so an incident has 실패 모델과 관측 규약이 같은 타입을 쓰므로, 사고 때 호출 하나에 대한 설명이 둘이 아니라 하나다.
one account of a call rather than two.
## Consequences ## 결과
**A whole class of retry bug becomes unrepresentable.** `GrpcRetryEligibility` reads all three axes **재시도 결함의 한 종류를 아예 나타낼 수 없게 된다.** `GrpcRetryEligibility`는 세 축 모두와 멱등성 profile을 읽는다.
plus the idempotency profile; a caller cannot reach "retry" from a status alone because the status status만으로는 입력이 아니므로, 호출자는 status만 보고 「재시도」에 닿을 수 없다.
alone is not an input.
**The fault lane has something to check.** `GrpcTransportEvidenceClassifier` turns a client's **장애 lane에 검사할 것이 생긴다.** `GrpcTransportEvidenceClassifier`가 client의 관찰을 증거로 바꾸고, 관찰하지 않은
observations into evidence and refuses to infer `NOT_SENT` from an unobserved state — and the lane 상태에서 `NOT_SENT`를 추론하기를 거절한다 — 그리고 lane은 mock이 아니라 호출 중간에 끊은 실제 연결에 대고 그것을
exercises it against a real connection dropped mid-call, not against a mock. 시험한다.
**Callers must handle a third outcome.** `COMPLETION_UNKNOWN` is not a failure and not a success, and **호출자는 세 번째 결과를 다뤄야 한다.** `COMPLETION_UNKNOWN`은 실패도 성공도 아니고, 둘 중 하나로 다루는 호출자는
a caller that treats it as either is wrong. `GrpcOperationStatusQuery` and `GrpcCompletionReconciler` 틀렸다. `GrpcOperationStatusQuery`와 `GrpcCompletionReconciler`는 그것을 푸는 일이 호출자에게 맡긴 숙제가 아니라
exist so that resolving it is a supported path rather than an exercise for the caller. 지원하는 경로가 되게 하려고 있다.
@@ -7,129 +7,106 @@
- 현재 정본: `docs/compatibility/grpc-support-matrix.md` - 현재 정본: `docs/compatibility/grpc-support-matrix.md`
<!-- 머리 블록 끝 --> <!-- 머리 블록 끝 -->
# ADR-GRPC-004: One retry owner, and keyed mutations need a durable ledger # ADR-GRPC-004: 재시도 소유자는 하나이고, 키가 있는 변경에는 durable 원장이 필요하다
- Status: accepted - 상태: 채택
- Date: 2026-08-30 - 날짜: 2026-08-30
- Scope: `:grpc:grpc-runtime` (was `grpc-policy`), `:grpc:grpc-operation-ledger-jpa`, `:grpc:grpc-core-api` - 범위: `:grpc:grpc-runtime`(예전 `grpc-policy`), `:grpc:grpc-operation-ledger-jpa`, `:grpc:grpc-core-api`
## Context ## 배경
Three layers can retry a gRPC call: the application, the channel's service config, and a service gRPC 호출을 재시도할 수 있는 계층이 셋 있다: 애플리케이션, channel의 service config, service mesh. 그 효과는 곱해진다.
mesh. Their effects multiply. Three attempts at each layer is twenty-seven requests for one call, and 계층마다 세 번 시도하면 호출 하나에 요청 스물일곱 개이고, 그 부하는 의존 대상이 이미 실패하고 있을 바로 그때 온다.
the load arrives exactly when the dependency is already failing.
Separately, a mutation that is safe to repeat needs somewhere to record that it ran. Without one, a 따로, 되풀이해도 안전한 변경에는 그것이 돌았다는 기록을 둘 곳이 필요하다. 없으면 응답을 잃은 뒤의 재시도는 효과를
retry after a lost response either duplicates the effect or drops it, and nothing distinguishes the 겹치게 하거나 버리게 되고, 나중에 둘을 구별할 것이 없다.
two afterwards.
## Decision ## 결정
**Exactly one retry owner per channel.** `GrpcRetryOwner` has four values including `NONE`, which is a **channel마다 재시도 소유자는 정확히 하나다.** `GrpcRetryOwner`에는 `NONE`을 포함해 값이 넷 있고, `NONE`은 빠뜨림이
decision rather than an omission. `GrpcServiceConfigPolicy` refuses an in-process retry entry when the 아니라 결정이다. `GrpcServiceConfigPolicy`는 소유자가 mesh이거나 아무도 아닐 때 프로세스 안 재시도 항목을 거절하고,
owner is the mesh or nobody, and `GrpcRetryOwnershipValidator` compares the service config's method `GrpcRetryOwnershipValidator`는 service config의 메서드 이름을 정책 catalog와 대조한다 — 이름이 바뀐 메서드는 그 재시도
names against the policy catalog — a renamed method leaves its retry entry matching nothing, silently, 항목이 소리 없이 아무것과도 맞지 않게 되고, 그 메서드는 channel 기본값으로 돈다.
and the method then runs with channel defaults.
**Retry eligibility reads the method, the evidence and the status together.** **재시도 자격은 메서드, 증거, status를 함께 읽는다.** `GrpcRetryEligibility`는 멱등이 아닌 메서드를 바로 거절하고,
`GrpcRetryEligibility` refuses a non-idempotent method outright, refuses any call whose stream stream이 앞부분을 전달한 호출을 모두 거절하며, 변경 요청의 `DEADLINE_EXCEEDED`나 보낸 뒤의 `UNAVAILABLE`을 재시도가
delivered a prefix, and turns a `DEADLINE_EXCEEDED` or post-send `UNAVAILABLE` mutation into 아니라 「먼저 완료를 풀어라」로 바꾼다.
"resolve the completion first" rather than a retry.
**A keyed mutation is retryable only with both a caller key and a durable ledger.** **키가 있는 변경은 호출자 키와 durable 원장이 둘 다 있을 때만 재시도할 수 있다.** `GrpcOperationLedger`는
`GrpcOperationLedger` is a port in `grpc-core-api`, so the policy layer can require durable `grpc-core-api`의 포트라서, 정책 계층이 데이터베이스에 의존하지 않고 durable 멱등성을 요구할 수 있다. 그 `claim` 계약은
idempotency without depending on a database. Its `claim` contract is a single atomic insert-or-read unique 제약에 대한 원자적 insert-or-read 하나다: `JpaGrpcOperationLedger`는 먼저 insert하고 제약 위반이면 읽는다.
against a unique constraint: `JpaGrpcOperationLedger` inserts first and reads on constraint violation, read-then-insert 구현에는 그것이 닫으려는 경쟁만큼 넓은 창이 있고, 두 시도를 동시에 돌리지 않는 모든 시험을
because a read-then-insert implementation has a window exactly as wide as the race it closes and 통과하기 때문이다.
passes every test that does not run two attempts concurrently.
The identity is caller fingerprint plus full method plus hashed key. All three are load-bearing: identity는 호출자 fingerprint + 전체 메서드 + hash한 키다. 셋 모두 꼭 필요하다: 호출자가 없으면 한 테넌트의 키가 다른
without the caller, one tenant's key suppresses another's write; without the method, a key reused 테넌트의 쓰기를 막는다. 메서드가 없으면 operation 사이에서 다시 쓴 키 때문에 둘째가 첫째의 재생이 된다.
across operations makes the second a replay of the first.
## Consequences ## 결과
**A budget bounds retries as a fraction of traffic.** `GrpcRetryBudget` degrades to roughly no **예산이 재시도를 traffic의 비율로 묶는다.** `GrpcRetryBudget`은 모든 것이 실패할 때 재시도가 거의 없는 쪽으로
retries when everything is failing, which is the behaviour that lets a dependency recover. 떨어진다. 그것이 의존 대상이 회복하게 하는 동작이다.
**The ledger and the mutation should commit together.** `JpaGrpcOperationLedger` carries no **원장과 변경은 함께 커밋해야 한다.** `JpaGrpcOperationLedger`는 일부러 트랜잭션 애너테이션을 달지 않는다:
transaction annotations, deliberately: a `REQUIRES_NEW` would put the claim in its own transaction and `REQUIRES_NEW`는 claim을 자기 트랜잭션에 넣어서, 쓰기는 durable한데 claim은 아닌 창을 다시 들인다.
reintroduce the window where the write is durable and the claim is not.
**A claim expires instead of blocking its key forever** (review 2026-11-01, 03-10). A claim still **claim은 키를 영원히 막지 않고 만료된다**(review 2026-11-01, 03-10). claim TTL이 지난 뒤에도 `IN_PROGRESS`인 claim은
`IN_PROGRESS` after the claim TTL is presumed abandoned by a dead owner, and the next retry of the same 죽은 주인이 버린 것으로 보고, 같은 요청의 다음 재시도가 `GrpcOperationLedger.reclaimStale`로 넘겨받는다 — 조건부
request takes it over with `GrpcOperationLedger.reclaimStale` — one conditional `UPDATE … WHERE state = 'IN_PROGRESS' AND claimed_at < :cutoff` 하나라서, 동시에 넘겨받기 둘이 오면 정확히 하나가 이긴다.
`UPDATE … WHERE state = 'IN_PROGRESS' AND claimed_at < :cutoff`, so of two concurrent takeovers exactly `reclaimFailed`와 같은 모양이다. TTL은 `GrpcIdempotencyInterceptor`의 `claimTtl` 인자이고, 키가 있는 모든 메서드의
one wins, the same shape as `reclaimFailed`. The TTL is the `claimTtl` argument of deadline보다 길지 않으면 만들 때 거절한다. 03-11 후속부터 starter는 `app.grpc.platform.operation-ledger-enabled=true`이면
`GrpcIdempotencyInterceptor`, refused at construction when it is not longer than every keyed method's interceptor를 조립하고 TTL을 `app.grpc.platform.operation-ledger-claim-ttl`(기본 5m)에서 가져온다. 생성자가 거절하는
deadline. Since the 03-11 follow-up the starter assembles the interceptor when TTL은 그 키 이름을 대며 기동을 실패시키고, `GrpcOperationLedger` bean 없이 flag를 켜도 기동이 실패한다.
`app.grpc.platform.operation-ledger-enabled=true` and takes the TTL from
`app.grpc.platform.operation-ledger-claim-ttl` (default 5m); a TTL the constructor refuses fails startup
naming that key, and an enabled flag without a `GrpcOperationLedger` bean fails startup too.
The takeover is safe only because the commit is recorded in the mutation's own transaction: then a 넘겨받기가 안전한 것은 커밋을 변경 자신의 트랜잭션 안에서 기록하기 때문뿐이다: 그러면 아직 `IN_PROGRESS`인 claim은
claim still `IN_PROGRESS` means the mutation never committed. An adopter that commits them separately 변경이 한 번도 커밋되지 않았다는 뜻이다. 둘을 따로 커밋하는 채택자는 버려진 claim을 모르는 결과로 만들고, 넘겨받기가
turns an abandoned claim into an unknown outcome, and a takeover can run the mutation twice. A takeover 변경을 두 번 돌릴 수 있다. 그저 느린 주인을 넘겨받아도 같은 일이 생긴다. 그래서 TTL은 deadline만이 아니라 키가 있는
of an owner that is merely slow does the same, which is why the TTL must exceed the slowest keyed 가장 느린 메서드보다 길어야 한다.
method and not just its deadline.
Rejected: an owner token with a heartbeat lease (the outbox lease model) — needed only when a keyed 버린 것: heartbeat lease를 단 owner token(outbox lease 모델) — 키가 있는 메서드가 어떤 고정 TTL보다 오래 돌 수 있을 때만
method can run longer than any fixed TTL; revisit when one exists. A sweeper job that deletes stale 필요하다. 그런 메서드가 생기면 다시 본다. 낡은 행을 지우는 sweeper job — 이 family에 없는 scheduler가 필요하고,
rows — it needs a scheduler this family does not have, and deleting a claim makes the next retry a claim을 지우면 다음 재시도가 시도를 버렸다는 기록 없는 새 claim이 된다.
fresh claim with no record that an attempt was abandoned.
**A taken-over owner is fenced by a claim token** (re-review 2026-11-03, RR-02-04). The owner a **넘겨받긴 주인은 claim token으로 막는다**(re-review 2026-11-03, RR-02-04). 넘겨받기가 죽었다고 보는 주인은 그저 느릴
takeover presumes dead may only be slow. Without knowing which attempt held the claim, its late 수 있다. 어느 시도가 claim을 쥐었는지 모르면, 그 주인의 늦은 `markFailed`가 새 시도의 claim을 `FAILED_TERMINAL`로
`markFailed` turned the new attempt's claim `FAILED_TERMINAL`, the next retry re-claimed it, and two 만들었고, 다음 재시도가 그것을 다시 claim해서 두 시도가 동시에 변경을 돌렸다. 늦은 `markCommitted`는 새 시도 옆에서
attempts ran the mutation at once; its late `markCommitted` committed beside the new attempt. Every 커밋했다. 이제 모든 claim은 `GrpcClaimToken`(`claim_attempt`, migration V003)을 싣는다: 첫 claim은 1이고,
claim now carries a `GrpcClaimToken` (`claim_attempt`, migration V003): 1 for the first claim, one more `reclaimFailed`나 `reclaimStale`마다 하나씩 늘어난다. `decide`는 `PROCEED`에서 그것을 돌려주고, `recordCommit` /
for each `reclaimFailed` or `reclaimStale`. `decide` returns it on `PROCEED`, and `recordCommit` / `recordFailure`가 그것을 되돌려 준다. 커밋이나 실패는 조건부
`recordFailure` hand it back. A commit or a failure is one conditional `UPDATE … WHERE state = 'IN_PROGRESS' AND claim_attempt = :attempt` 하나다: claim을 잃은 시도의 커밋은 예외로 거절해서
`UPDATE … WHERE state = 'IN_PROGRESS' AND claim_attempt = :attempt`: a commit by an attempt that lost 그 업무 트랜잭션이 롤백되고, 그런 시도의 실패는 무시한다(`markFailed`가 false를 돌려준다). 같은 조건부 update가 JPA
the claim is refused with an exception, so its business transaction rolls back; a failure by one is 커밋 경쟁도 닫는다 — load-check-save에서는 둘 다 `IN_PROGRESS`를 읽은 커밋 둘이 둘 다 썼다. 이제 정확히 하나만 맞는다.
ignored (`markFailed` returns false). The same conditional update closes the JPA commit race — insert와 read 사이에 충돌 행이 지워진 claim은 호출을 실패시키지 않고 insert를 한 번 다시 시도한다.
load-check-save let two commits that both read `IN_PROGRESS` both write; now exactly one matches.
A claim whose conflicting row is purged between insert and read retries the insert once instead of
failing the call.
`release(identity, claimToken)` is fenced the same way (re-review 2026-11-03 round 2, RR-01-15): it is a `release(identity, claimToken)`도 같은 방식으로 막는다(re-review 2026-11-03 round 2, RR-01-15): 조건부
conditional `DELETE … WHERE state = 'IN_PROGRESS' AND claim_attempt = :attempt` and returns whether it `DELETE … WHERE state = 'IN_PROGRESS' AND claim_attempt = :attempt`이고 지웠는지를 돌려준다. 예전에는 키만으로 지웠기
deleted. It used to delete by key alone, so any caller could erase the claim of the attempt that held 때문에, 아무 호출자나 그것을 쥔 시도의 claim이나 재시도가 재생하는 끝난 레코드를 지울 수 있었다. counter는 행 안에
it, or a finished record a retry replays. The counter lives in the row, so a deleted row's key starts 있으므로 지운 행의 키는 다시 attempt 1에서 시작한다: token은 행 하나의 시도들을 가르지, 삭제를 넘는 시도들을 가르지
again at attempt 1: the token separates the attempts of one row, not attempts across a delete. Both 않는다. 그래서 두 삭제를 모두 제한한다 — release는 주인이 사라졌다고 아는 claim에만, purge는 어떤 재시도보다 오래 전에
deletions are limited accordingly — release only for a claim whose owner is known to be gone, purge 끝난 행에만. 버린 것: 포트에서 `release`를 빼기(`markFailed` 뒤 `reclaimFailed`는 counter를 지키지만, 다른 요청을 위해
only for rows finished longer ago than any retry. Rejected: dropping `release` from the port 키를 풀어야 하는 배포에는 다른 길이 없다), counter를 지키는 tombstone 행(지울 두 번째 상태가 생기는데, 그 창은 두 제한이
(`markFailed` then `reclaimFailed` keeps the counter, but a deployment that must free a key for a 이미 닫는다).
different request has no other path), and a tombstone row that keeps the counter (a second state to
purge, for a window the two limits already close).
Chosen over the claim moment as the token (`WHERE claimed_at = :claimedAt`), which needs no column: token으로 claim 시각(`WHERE claimed_at = :claimedAt`)을 쓰는 안보다 이것을 골랐다. 시각은 열이 따로 필요 없지만,
PostgreSQL stores microseconds while `Instant` carries nanoseconds, so the token a caller holds and PostgreSQL은 마이크로초를 저장하고 `Instant`는 나노초를 싣는다. 그래서 호출자가 쥔 token과 저장된 것이 반올림만큼
the one stored can differ by rounding, and two processes' clocks can give two attempts the same 다를 수 있고, 두 프로세스의 시계가 두 시도에 같은 시각을 줄 수 있다. counter에는 두 문제가 다 없다. 위 heartbeat lease는
moment. The counter has neither problem. The heartbeat lease above stays rejected for the same reason 앞과 같은 이유로 계속 버린다. token은 그것 없이 막는다.
as before; the token fences without one.
**What `operation-ledger-enabled=true` promises (03-11 (b), recorded 2026-11-03, RR-02-07).** The **`operation-ledger-enabled=true`가 약속하는 것(03-11 (b), 2026-11-03 기록, RR-02-07).** 2026-11-01 리뷰는 (a) flag를
2026-11-01 review offered (a) delete the flag and judge by whether a ledger bean exists, or (b) keep the 지우고 원장 bean이 있는지로 판단하기와 (b) flag를 두고 starter가 그것으로 판정 함수를 조립하기를 내놓았다. (b)를
flag and have the starter assemble the decision function from it. (b) is kept: the assembly and the 지킨다: 조립과 TTL 검증이 채택자마다가 아니라 한곳에 있다. (a)는 거짓 약속을 없애되 조립까지 함께 없애기 때문에
TTL validation live in one place instead of in every adopter. (a) was rejected because it removes the 버렸다. 한계는 남고, 운영자가 그것을 만나는 곳에 적는다: starter는 서버를 만들지 않으므로 flag는 판정 함수만
false promise only by removing the assembly with it. The limit stays and is stated where an operator 조립하고, 채택자의 `IDEMPOTENCY` 단계 interceptor나 service adapter가 `decide`와 `recordCommit`을 부를 때 비로소 키가
meets it: the starter builds no server, so the flag assembles the decision function only, and keys are 지켜진다. 키가 있는 메서드에 대한 `GrpcPlatformStartupValidator`의 거절이 바로 그것을 말한다. 돌고 있는 프로세스는 그
honoured once the adopter's `IDEMPOTENCY` stage interceptor or service adapter calls `decide` and 단계가 있는지 볼 수 없으니, validator는 그것을 검사한다고 주장하지 않는다.
`recordCommit`. `GrpcPlatformStartupValidator`'s refusal for a keyed method says exactly that; a running
process cannot see whether the stage exists, so the validator does not claim to check it.
**Finished rows are purged after a retention; in-progress rows never are** (03-10 follow-up). **끝난 행은 보존 기간 뒤에 지우고, 진행 중인 행은 절대 지우지 않는다**(03-10 후속).
`GrpcOperationLedger.purgeCompletedBefore(cutoff, limit)` deletes at most `limit` `COMMITTED` or `GrpcOperationLedger.purgeCompletedBefore(cutoff, limit)`는 cutoff 전에 끝난 `COMMITTED`나 `FAILED_TERMINAL` 행을 오래된
`FAILED_TERMINAL` rows that completed before the cutoff, oldest first — on PostgreSQL one bounded 것부터 많아야 `limit`개 지운다 — PostgreSQL에서는 migration V002의 부분 index가 받쳐 주는 한계 있는
`DELETE … WHERE storage_key IN (SELECT … LIMIT … FOR UPDATE SKIP LOCKED)` served by the partial index `DELETE … WHERE storage_key IN (SELECT … LIMIT … FOR UPDATE SKIP LOCKED)` 하나다.
of migration V002. `GrpcOperationLedgerRetention.purgeExpired(now)` applies `GrpcOperationLedgerRetention.purgeExpired(now)`가 `app.grpc.platform.operation-ledger-retention`(기본 24h, HTTP 멱등성
`app.grpc.platform.operation-ledger-retention` (default 24h, the HTTP idempotency replay TTL) in 재생 TTL)을 batch로 적용한다. 레코드가 지워진 뒤의 재시도는 새 claim이고 다시 돈다. 그래서 보존 시간은 호출자의 재시도
batches. A retry after its record was purged is a fresh claim and runs again, so the retention must 창보다 길어야 한다. 지우기 일정은 채택자가 잡는다. starter는 정책만 조립한다. 예약된 bean은 모든 배포에 scheduler를
exceed the callers' retry window. The adopter schedules the purge; the starter assembles the policy 강요하고, starter는 어느 replica가 돌려야 하는지 알 수 없기 때문이다.
only, because a scheduled bean would force a scheduler onto every deployment and the starter cannot
know which replica should run it.
**A key reused for a different request is a caller error, not a duplicate.** The stored request **다른 요청에 다시 쓴 키는 중복이 아니라 호출자 오류다.** 저장된 요청 fingerprint가 그것을 소리 없이 첫 요청의 답을
fingerprint turns that into `FAILED_PRECONDITION` rather than silently returning the first request's 돌려주는 대신 `FAILED_PRECONDITION`으로 바꾼다.
answer.
@@ -7,53 +7,46 @@
- 현재 정본: `docs/compatibility/grpc-support-matrix.md` - 현재 정본: `docs/compatibility/grpc-support-matrix.md`
<!-- 머리 블록 끝 --> <!-- 머리 블록 끝 -->
# ADR-GRPC-005: One writer per stream, a bounded queue, and resume that refuses to guess # ADR-GRPC-005: stream마다 쓰는 쪽 하나, 한계 있는 queue, 짐작하기를 거절하는 resume
- Status: accepted - 상태: 채택
- Date: 2026-08-30 - 날짜: 2026-08-30
- Scope: `:grpc:grpc-runtime` (was `grpc-policy`) - 범위: `:grpc:grpc-runtime`(예전 `grpc-policy`)
## Context ## 배경
`StreamObserver` is not thread-safe, and the failure when two producers call `onNext` concurrently is `StreamObserver`는 thread-safe가 아니다. 두 producer가 동시에 `onNext`를 부를 때의 실패는 예외가 아니다 — 섞인 바이트이고,
not an exception — it is interleaved bytes, which a client decodes as a corrupt message or, worse, as client는 그것을 깨진 메시지로, 더 나쁘게는 받지 말았어야 할 유효한 메시지로 decode한다.
a valid one it should never have received.
Two further properties of server streams are easy to get wrong in ways that look healthy. A consumer server stream에는 건강해 보이는 방식으로 틀리기 쉬운 성질이 둘 더 있다. 뒤처진 소비자는 stream을 끝내거나 메시지를 소리
that falls behind either terminates the stream or silently loses messages, and the second leaves a 없이 잃는데, 둘째는 client에게 멀쩡해 보이지만 변경이 빠진 stream을 남긴다. 그리고 재연결은 서버가 아직 재생할 수 있는
client with a stream that appears fine and is missing changes. And a reconnect either continues from 위치에서 이어 가거나, 더는 없는 것을 건너뛴다.
a position the server can still replay, or skips whatever is no longer there.
## Decision ## 결정
**A bounded queue drained by one writer.** `GrpcSerializedStreamWriter` accepts messages from any **쓰는 쪽 하나가 비우는 한계 있는 queue.** `GrpcSerializedStreamWriter`는 어느 스레드에서든 메시지를 받고, synchronized인
thread and hands them to the transport only from `flush`, which is synchronized. `write` returning `flush`에서만 전송에 넘긴다. `write`가 `ACCEPTED`를 돌려주는 것은 줄 세웠다는 뜻이고, 이름을 일부러 `sent`로 하지
`ACCEPTED` means queued, and the name is deliberately not `sent`: the transport call returns as soon 않았다: 전송 호출은 바이트를 넘기자마자 돌아오므로, 여기 어떤 메서드도 전달을 정직하게 알릴 수 없다.
as bytes are handed over, so no method here can honestly report delivery.
**Both a message bound and a byte bound.** Either alone is unbounded in the other dimension. **메시지 한계와 바이트 한계를 둘 다.** 하나만 두면 다른 차원으로는 한계가 없다. `GrpcFlowControlPolicy`는 전송 자신의
`GrpcFlowControlPolicy` also takes the transport's own readiness signal, because a writer that relies readiness 신호도 받는다. queue 한계에만 기대는 쓰는 쪽은 메모리를 할당할 수 있는 만큼 빨리 만들어 내기 때문이다.
only on its queue bound produces as fast as it can allocate.
**Termination is the default for a slow consumer.** `GrpcSlowConsumerPolicy.DROP_OLDEST` exists for **느린 소비자에게는 끝내기가 기본이다.** `GrpcSlowConsumerPolicy.DROP_OLDEST`는 업무 뜻이 손실을 견디는 feed를 위해
feeds whose business meaning tolerates loss, and is not the default, because a client cannot detect 있고 기본값이 아니다. client는 버려진 메시지를 알아챌 수 없기 때문이다: client가 보는 순번은 보내진 것의 순번이다.
dropped messages: the sequence numbers it sees are the ones it was sent.
**Resume is refused rather than faked.** `GrpcStreamGapDetector` requires a signed, unexpired token **resume은 꾸며 내지 않고 거절한다.** `GrpcStreamGapDetector`는 서명됐고 만료되지 않았으며 호출자·필터 fingerprint가
whose caller and filter fingerprints match the current request, refuses one whose snapshot version 지금 요청과 맞는 token을 요구하고, snapshot version이 움직인 token을 거절하며, cursor가 보존한 이력보다 앞서면
moved, and returns `FULL_RESYNC_REQUIRED` when the cursor predates retained history. `GrpcResumeToken` `FULL_RESYNC_REQUIRED`를 돌려준다. `GrpcResumeToken`은 key id를 싣는다. 그래서 서명 키를 바꿔도 아직 쓰이는 모든 token이
carries a key id so the signing key can rotate without invalidating every outstanding token. 무효가 되지 않는다.
## Consequences ## 결과
**A stream carries an envelope, not a bare payload.** `GrpcStreamEnvelope` holds the stream id, **stream은 맨 payload가 아니라 envelope을 싣는다.** `GrpcStreamEnvelope`은 stream id, generation, 순번, snapshot version,
generation, sequence, snapshot version and resume token, because resume, gap detection and drain all resume token을 가진다. resume, 빈틈 찾기, 비우기가 모두 위치와 generation을 필요로 하기 때문이다.
need a position and a generation.
**Four clocks, not one.** `GrpcStreamLifetimePolicy` separates setup deadline, idle timeout, max **시계는 하나가 아니라 넷이다.** `GrpcStreamLifetimePolicy`는 준비 deadline, idle timeout, 최대 지속 시간, heartbeat
duration and heartbeat interval, and refuses combinations where one can never fire. Merging any pair 간격을 나누고, 하나가 절대 울릴 수 없는 조합을 거절한다. 어느 둘을 합치든 익숙한 결함이 나온다: 최대 지속 시간으로 쓴
produces a familiar bug: an idle timeout used as a max duration kills healthy busy streams. idle timeout은 건강하게 바쁜 stream을 죽인다.
**A heartbeat is a liveness signal and nothing else.** It is not an application acknowledgement and **heartbeat는 살아 있다는 신호이고 그 밖의 무엇도 아니다.** 애플리케이션 확인 응답도 순서 보장도 아니다.
not an ordering guarantee; `GrpcStreamHeartbeat` says so in the place somebody would otherwise reuse `GrpcStreamHeartbeat`가 누가 그것을 다르게 다시 쓸 법한 자리에서 그렇게 말한다.
it.
@@ -7,71 +7,61 @@
- 현재 정본: `docs/compatibility/grpc-support-matrix.md` - 현재 정본: `docs/compatibility/grpc-support-matrix.md`
<!-- 머리 블록 끝 --> <!-- 머리 블록 끝 -->
# ADR-GRPC-006: Stable discovery is DNS and static, and a Kubernetes profile names who balances # ADR-GRPC-006: Stable discovery는 DNS와 static이고, Kubernetes profile은 누가 분산하는지 이름으로 댄다
- Status: accepted - 상태: 채택
- Date: 2026-08-31 - 날짜: 2026-08-31
- Scope: `:grpc:grpc-runtime` (was `grpc-discovery`, `grpc-client`) - 범위: `:grpc:grpc-runtime`(예전 `grpc-discovery`, `grpc-client`)
## Context ## 배경
A gRPC channel's discovery configuration has a failure mode with no runtime symptom: it works, and gRPC channel의 discovery 설정에는 런타임 증상이 없는 실패 방식이 있다: 동작은 하는데, 대시보드가 말하는 일을 하지 않는다.
it does not do what the dashboard says it does.
The specific case is `round_robin` over a Kubernetes Service ClusterIP. The Service is one virtual 구체적인 경우는 Kubernetes Service ClusterIP 위의 `round_robin`이다. Service는 가상 주소 하나라서 resolver가 endpoint 하나를
address, so the resolver returns one endpoint and the client-side balancer has nothing to rotate 돌려주고 client 쪽 분산기는 돌려 가며 보낼 대상이 없다. kube-proxy는 연결할 때 pod를 고르고, HTTP/2 연결은 오래 살기
across; kube-proxy picks a pod at connect time, and an HTTP/2 connection is long-lived, so every 때문에, 그 client의 모든 요청이 연결이 사는 동안 같은 pod로 간다. 실패하는 것은 없다. 설정은 `round_robin`이라고 말하고,
request from that client goes to the same pod for the life of the connection. Nothing fails. The metric은 요청이 pod가 아니라 client 사이에 퍼진 것을 보여 주며, 「client 쪽 부하 분산을 한다」는 결론은 아무도 확인할
configuration says `round_robin`, the metrics show requests spread across clients rather than pods, 계기가 없는 방식으로 틀렸다.
and the conclusion "we have client-side load balancing" is wrong in a way nobody is prompted to
check.
The mirror-image mistake is `pick_first` over a headless record, which pins a client to one pod out 거울상 실수는 headless record 위의 `pick_first`다. 많은 pod 중 하나에 client를 묶는다.
of many.
Separately, a service mesh changes who owns retries, and a deployment that adds mesh routing without 따로, service mesh는 재시도를 누가 가지는지 바꾸고, mesh 라우팅을 더하면서 자기 재시도 정책을 빼지 않은 배포는 효과가
removing its own retry policy has two retriers whose effects multiply. 곱해지는 재시도자 둘을 가진다.
## Decision ## 결정
**Stable resolvers are Static, DNS and Unix domain socket; Stable load balancing is `pick_first` and **Stable resolver는 Static, DNS, Unix domain socket이고, Stable 부하 분산은 `pick_first`와 `round_robin`이다.**
`round_robin`.** `GrpcDiscoveryPolicyValidator.requireStableScheme` refuses `xds`, `consul`, `etcd` `GrpcDiscoveryPolicyValidator.requireStableScheme`은 `xds`, `consul`, `etcd`, `eureka`를 이름으로 거절하고, 그것이 모르는
and `eureka` by name, with a message saying they are Advanced capabilities with their own control scheme이 아니라 자기 control plane과 승격 gate를 가진 Advanced capability라고 메시지로 말한다.
plane and promotion gate rather than unknown schemes.
**The pairing is checked against the resolved address count, not against intent.** **짝 맞춤은 의도가 아니라 해석된 주소 수와 대조한다.** `GrpcResolverProfile`은 `expectedAddressCount`를 싣고,
`GrpcResolverProfile` carries `expectedAddressCount`, and `GrpcStableLoadBalancer.effective` answers `GrpcStableLoadBalancer.effective`가 그 수의 endpoint 위에서 정책이 무언가를 분산하는지 답한다. 주소 하나 위의
whether the policy distributes anything over that many endpoints. A `round_robin` profile over one `round_robin` profile은 보고되는 위반이고, 그 메시지는 그것이 일어나지 않는 퍼뜨리기를 설명한다고 말한다.
address is a reported violation whose message says it describes spreading that is not happening.
**A Kubernetes deployment names its routing mode**, and the mode implies both the balancer and the **Kubernetes 배포는 자기 라우팅 모드를 이름으로 대고**, 그 모드가 분산기와 재시도 소유자를 둘 다 정한다.
retry owner. `GrpcKubernetesRoutingMode` has three values — `K8S_VIP`, `K8S_HEADLESS`, `MESH` — and `GrpcKubernetesRoutingMode`에는 값이 셋 있다 — `K8S_VIP`, `K8S_HEADLESS`, `MESH` — 그리고 `GrpcKubernetesProfile`은 재시도
`GrpcKubernetesProfile` refuses a mesh profile whose retry owner retries in-process. 소유자가 프로세스 안에서 재시도하는 mesh profile을 거절한다.
**A profile that carries long-lived streams must state a reconnect budget and a readiness drain **오래 사는 stream을 싣는 profile은 재연결 예산과 readiness 비우기 유예를 밝혀야 한다.** stream은 사는 내내 client를 pod
grace.** A stream pins a client to one pod for its whole life, so every rollout, eviction and 하나에 묶으므로, 모든 rollout, eviction, scale-down이 그것을 끝낸다. `GrpcKubernetesProfileValidator`는 긴 stream을 싣는
scale-down ends it. `GrpcKubernetesProfileValidator` additionally reports a VIP profile carrying VIP profile과, 재연결 예산보다 짧은 비우기 유예도 알린다 — 후자는 client가 다른 곳으로 재연결을 마치기 전에 pod가 응답을
long streams, and a drain grace shorter than the reconnect budget — the second means the pod stops 멈춘다는 뜻이다.
serving before its clients have finished reconnecting elsewhere.
**A DNS profile must refresh.** `GrpcResolverProfile` refuses a zero refresh interval on DNS, **DNS profile은 새로 고쳐야 한다.** `GrpcResolverProfile`은 DNS에서 새로 고침 간격 0을 거절한다. 기동 때 한 번 해석한
because a channel that resolved once at startup keeps sending to addresses that stopped existing an channel은 한 시간 전에 없어진 주소로 계속 보내고, 그 결과인 `UNAVAILABLE`은 rollout이 끝난 지 한참 뒤에도 건강하지 않은
hour ago, and the resulting `UNAVAILABLE` looks like an unhealthy deployment long after the rollout 배포처럼 보인다.
finished.
## Consequences ## 결과
**Two validators, not one.** `GrpcDiscoveryPolicyValidator` asks whether a balancer does anything **validator는 하나가 아니라 둘이다.** `GrpcDiscoveryPolicyValidator`는 분산기가 자기가 볼 주소 위에서 무언가를 하는지
over the addresses it will see; `GrpcKubernetesProfileValidator` asks whether the deployment shape, 묻는다. `GrpcKubernetesProfileValidator`는 배포 모양, 재시도 소유자, stream 의무가 맞는지 묻는다. 배포는 resolver profile이
the retry owner and the stream obligations agree. A deployment can have a coherent resolver profile 앞뒤가 맞으면서도 재시도를 두 곳에 둘 수 있다. 그래서 둘을 합치면 한 답이 다른 답을 가린다.
and still have put retries in two places, so merging them would let one answer hide the other.
**`expectedAddressCount` has to come from somewhere.** It is a declared number, and a declaration can **`expectedAddressCount`는 어딘가에서 와야 한다.** 선언한 숫자이고, 선언은 틀릴 수 있다. 그래도 아무것도 비교하지 않는
be wrong. It is still better than the alternative, which is not comparing anything: a wrong 대안보다 낫다: 틀린 선언은 누가 적어 둔 틀린 말이고, 빠진 선언은 아무도 묻지 않은 질문이다.
declaration is a wrong statement somebody wrote down, and a missing one is a question nobody asked. `GrpcChannelProfileValidator`는 기동 때 알 수 있는 곳에서는 해석된 수를 받고, 알 수 없는 곳에서는 짐작해서 아직 해석할 수
`GrpcChannelProfileValidator` takes resolved counts where they are known at startup and skips the 없는 이름에서 실패하는 대신 검사를 건너뛴다.
check where they are not, rather than guessing and failing on a name that cannot be resolved yet.
**xDS is reachable, and not by this route.** It lives in `grpc-advanced` (package `resilience`/`xds`) behind its **xDS에는 닿을 수 있지만, 이 길로는 아니다.** xDS는 `grpc-advanced`(패키지 `resilience`/`xds`)에서 자기 capability flag와
capability flag and its production approval, and `GrpcXdsStartupGuard.advertisableAsStableSupport()` 운영 승인 뒤에 있고, `GrpcXdsStartupGuard.advertisableAsStableSupport()`가 false를 돌려주므로 Stable 지원 설명이 조용히
returns false so the Stable support statement cannot widen quietly. See ADR-GRPC-ADV-001. 넓어질 수 없다. ADR-GRPC-ADV-001을 본다.
@@ -7,60 +7,51 @@
- 현재 정본: `docs/compatibility/grpc-advanced-support-matrix.md` - 현재 정본: `docs/compatibility/grpc-advanced-support-matrix.md`
<!-- 머리 블록 끝 --> <!-- 머리 블록 끝 -->
# ADR-GRPC-ADV-001: Each advanced capability has its own flag, its own grade and its own promotion # ADR-GRPC-ADV-001: advanced capability마다 자기 flag, 자기 등급, 자기 승격이 있다
- Status: accepted - 상태: 채택
- Date: 2026-08-30 - 날짜: 2026-08-30
- Scope: `:grpc-advanced:*` - 범위: `:grpc-advanced:*`
## Context ## 배경
The advanced plan covers sixteen capabilities that differ by orders of magnitude in what they bring advanced 계획은 capability 열여섯을 다룬다. 그것들이 함께 가져오는 것은 몇 자릿수씩 다르다. gRPC-Web은 proxy를 더한다.
with them. gRPC-Web adds a proxy. Reactor adds a dependency. xDS adds a control plane, its outage Reactor는 의존 하나를 더한다. xDS는 control plane, 그 장애 방식, 자기 보안 경계, 자기 버전 어긋남을 더한다. hedging은 운영
modes, its own security boundary and its own version skew. Hedging duplicates production traffic. traffic을 겹친다.
Bundling them under one flag makes enabling the cheapest of those the same decision as enabling the 그것들을 flag 하나로 묶으면 가장 싼 것을 켜는 일이 가장 무거운 것을 켜는 일과 같은 결정이 된다.
most consequential.
## Decision ## 결정
**One flag per capability**, under `ca-skeleton.grpc.advanced.<capability>.enabled`, all off by **capability마다 flag 하나.** `ca-skeleton.grpc.advanced.<capability>.enabled` 아래에 있고, 기본은 모두 꺼짐이다.
default.
**Four grades.** `ADVANCED_STABLE` starts on its flag; `EXPERIMENTAL` additionally needs a separate **등급 넷.** `ADVANCED_STABLE`은 flag로 시작한다. `EXPERIMENTAL`은 따로 운영 승인도 필요하다. flag는 누가 그 기능을 원했다는
production approval, because the flag says somebody wanted the feature and the approval says somebody 뜻이고, 승인은 누가 그 장애 방식이 다 밝혀지지 않았음을 받아들였다는 뜻이기 때문이다. `WATCH`는 아예 시작할 수 없다.
accepted that its failure modes are not fully characterised; `WATCH` cannot start at all; `DISABLED` `DISABLED`는 거둬들인 것이다.
is withdrawn.
`GrpcAdvancedModuleGuard` distinguishes the three refusals — flag unset, grade unstartable, `GrpcAdvancedModuleGuard`는 세 거절 — flag 없음, 시작할 수 없는 등급, 운영 승인 없음 — 을 구별한다. 경우마다 고치는 법이
production unapproved — because the remedy differs in each case. 다르기 때문이다.
**Promotion evidence is per capability.** `GrpcAdvancedPromotionEvidence` is one record per **승격 증거는 capability마다다.** `GrpcAdvancedPromotionEvidence`는 capability마다 record 하나라서, 어떤 승격도 다른 것을
capability, so no promotion can drag another along; 끌고 가지 못한다. `GrpcAdvancedPromotionGate.capabilitiesDraggedAlong`은 빈 목록을 돌려주고, 그것은 주장이 아니라 시험한
`GrpcAdvancedPromotionGate.capabilitiesDraggedAlong` returns an empty list, and that is a tested 성질이다. (2026-09-28: gate 클래스는 자기 시험 밖에서 부르는 것이 없어서 지웠다 — review 2026-09-24 S5-lead-4.
property rather than a claim. (2026-09-28: the gate classes were removed because nothing outside capability별 규칙은 `docs/runbooks/grpc-advanced-capabilities.md`의 리뷰 규칙으로 남는다.) 문턱은 둘이다:
their own tests called them — review 2026-09-24 S5-lead-4. The per-capability rule stands as a `ADVANCED_STABLE`에는 7일 soak와 완전한 증거, Stable 기본값에는 30일. 후자는 모든 배포가 그 capability의 의존과 장애 방식을
review rule in `docs/runbooks/grpc-advanced-capabilities.md`.) Two thresholds: seven days of soak plus complete evidence for 받는다는 뜻이기 때문이다.
`ADVANCED_STABLE`, thirty for a Stable default, because the second means every deployment gets the
capability's dependencies and its failure modes.
**Infrastructure is named per capability.** `GrpcAdvancedInfrastructureTestkit` records that **기반 시설은 capability마다 이름으로 댄다.** `GrpcAdvancedInfrastructureTestkit`은 gRPC-Web에는 proxy가, Servlet에는
gRPC-Web needs a proxy, Servlet needs a container, xDS needs a stoppable control plane and Kotlin container가, xDS에는 멈출 수 있는 control plane이, Kotlin에는 toolchain이 필요하다고 적는다. 기반 시설 없이 도는 suite는
needs a toolchain. A suite that runs without its infrastructure passes and establishes nothing, which 통과하고 아무것도 세우지 않는다. 없는 것보다 나쁘다.
is worse than not having one.
## Consequences ## 결과
**The Kotlin adapter fails closed here, and says why.** This repository has no Kotlin toolchain, so **Kotlin 어댑터는 여기서 실패하면 닫히고, 이유를 말한다.** 이 저장소에는 Kotlin toolchain이 없어서
`GrpcKotlinCompatibilityGate.supportableHere()` returns false. The four contract requirements — one `GrpcKotlinCompatibilityGate.supportableHere()`가 false를 돌려준다. 계약 요구 넷 — schema 출처 하나, coroutine 취소 전파,
schema source, coroutine cancellation propagation, Flow backpressure inside the Stable bounds, Stable 한계 안의 Flow backpressure, 플랫폼 증거 타입 보존 — 은 검사할 수 있고 검사한다. 빠진 것은 compile lane뿐이다.
platform evidence types preserved — are checkable and are checked; only the compile lane is missing.
**Edition 2026 cannot be used however its watch report reads.** `GrpcEdition2026Guard` is not **Edition 2026은 그 watch 보고가 무어라 하든 쓸 수 없다.** `GrpcEdition2026Guard`는 보고에 따라 달라지지 않는다. 상태 기록이
conditional on the report, because letting a status record also authorise use means a schema moves 사용까지 허락하게 두면, 누가 필드 넷을 SUPPORTED로 표시하는 순간 schema가 승격 결정도, 쓰는 쪽 옮기기도, ADR도 없이 그
onto an edition the moment somebody marks four fields SUPPORTED, with no promotion decision, no edition으로 옮겨 가기 때문이다.
consumer migration and no ADR.
**xDS is not part of the Stable support statement.** It works, behind its flag and its approval; **xDS는 Stable 지원 설명의 일부가 아니다.** flag와 승인 뒤에서 동작한다. `GrpcXdsStartupGuard.advertisableAsStableSupport()`가
`GrpcXdsStartupGuard.advertisableAsStableSupport()` returns false so a support matrix cannot widen false를 돌려주므로 support matrix가 조용히 넓어질 수 없다.
quietly.
@@ -7,38 +7,34 @@
- 현재 정본: `docs/jpa/repository-adaptation.md` - 현재 정본: `docs/jpa/repository-adaptation.md`
<!-- 머리 블록 끝 --> <!-- 머리 블록 끝 -->
# ADR-JPA-001 — The domain owns the persistence model # ADR-JPA-001 — 영속 모델은 도메인이 가진다
- Status: Accepted - 상태: 채택
- Date: 2026-08-11 - 날짜: 2026-08-11
- Design: §10.1, §23.3 - 설계: §10.1, §23.3
## Context ## 배경
A persistence platform can either own the repository abstraction — a `GenericRepository<T, ID>` 영속 플랫폼은 repository 추상 — 모든 aggregate가 상속하는 `GenericRepository<T, ID>` — 을 가질 수도 있고, 도메인이 스스로
every aggregate inherits — or provide only the pieces domains assemble themselves. 조립할 조각만 줄 수도 있다.
## Decision ## 결정
The domain owns entities, embeddables, repositories, queries, index requirements, and lock, 엔티티, embeddable, repository, query, index 요구, lock·soft-delete·감사 정책은 도메인이 가진다. 플랫폼은 범용 CRUD
soft-delete, and audit policy. The platform provides no generic CRUD repository and no base repository도 기반 repository도 주지 않는다. `JpaRepositoryFragmentSupport`는 있지만 `save`, `findById`, `findAll`, `delete`가
repository. `JpaRepositoryFragmentSupport` exists, has no `save`, `findById`, `findAll`, or 없고, 그것을 얻지 못하게 강제한다.
`delete`, and is enforced not to acquire them.
## Consequences ## 결과
A generic base repository has one property that looks like a benefit and is not: every aggregate 범용 기반 repository에는 이득처럼 보이지만 이득이 아닌 성질이 하나 있다: 모든 aggregate가 같은 operation을 받는다. 그러면
gets the same operations. That means each aggregate is offered operations that may be wrong for it — aggregate마다 자기에게 틀릴 수 있는 operation을 받게 된다 — append-only 원장의 `delete`, 결코 작지 않을 테이블의 `findAll` —
a `delete` on an append-only ledger, a `findAll` on a table that will never be small — and, worse, 그리고 더 나쁘게, 한 aggregate의 나중 요구가 공용 기반을 바꾸고 그래서 아무도 리뷰하지 않은 aggregate의 동작을 바꾼다.
one aggregate's later requirement changes the shared base and therefore changes behaviour for
aggregates nobody reviewed.
Spring Data already implements CRUD. Re-implementing it adds a layer whose only function is to be Spring Data는 이미 CRUD를 구현한다. 그것을 다시 구현하면 빠져나가기 더 어렵게 만드는 것만이 하는 일인 계층이 더해진다.
harder to opt out of.
The cost is a small amount of repetition: each domain declares the repository interface it needs. 비용은 약간의 되풀이다: 도메인마다 필요한 repository 인터페이스를 선언한다. 그 되풀이가 aggregate마다 영속 surface를 리뷰할
That repetition is the thing that makes each aggregate's persistence surface reviewable. 수 있게 만든다.
## Enforcement ## 강제
`JpaArchitectureRules.noGenericRepository()`; `JpaRepositoryFragmentSupportTest`. `JpaArchitectureRules.noGenericRepository()`, `JpaRepositoryFragmentSupportTest`.
+25 -29
View File
@@ -8,43 +8,39 @@
- 대체됨: `docs/capability-status.md` - 대체됨: `docs/capability-status.md`
<!-- 머리 블록 끝 --> <!-- 머리 블록 끝 -->
# ADR-JPA-002 — Retry re-runs the whole use case # ADR-JPA-002 — 재시도는 유스케이스 전체를 다시 돌린다
- Status: Superseded (2026-09-25) — the retry engine this ADR describes - 상태: 대체됨(2026-09-25) — 이 ADR이 설명하는 재시도 엔진(`FullTransactionRetryCoordinator`, `JpaTransactionExecutor`)은
(`FullTransactionRetryCoordinator`, `JpaTransactionExecutor`) was removed. `SpringTransactionPort` 지웠다. `SpringTransactionPort`는 아무것도 재시도하지 않는다. 재시도하는 호출자는 여전히 유스케이스 전체를 다시 돌리고,
retries nothing; a caller that retries still re-runs the whole use case, which is the part of this 이 결정 중 그 부분이 남는다. 마지막 커밋은 `docs/capability-status.md`에 있다.
decision that stands. The last commit is in `docs/capability-status.md`. - 날짜: 2026-08-11
- Date: 2026-08-11 - 설계: §19.2
- Design: §19.2
## Context ## 배경
Optimistic conflicts, deadlocks, and serialization failures are recoverable. The question is what 낙관적 충돌, 교착, serialization 실패는 회복할 수 있다. 질문은 무엇을 단위로 재시도하느냐다: 실패한 문장, 트랜잭션, 또는
unit gets retried: the failed statement, the transaction, or the use case. 유스케이스.
## Decision ## 결정
The whole use case, in a new transaction with a new Persistence Context. 유스케이스 전체를, 새 Persistence Context를 가진 새 트랜잭션에서. `FullTransactionRetryCoordinator`는 시도마다
`FullTransactionRetryCoordinator` re-enters `JpaTransactionExecutor` for every attempt, and the `JpaTransactionExecutor`에 다시 들어가고, 재시도 advice는 Spring 트랜잭션 advice 바깥으로 순서를 잡아 시도마다 새
retry advice is ordered outside Spring's transaction advice so each attempt begins a new 트랜잭션을 시작한다.
transaction.
## Consequences ## 결과
Statement-level retry is wrong for exactly the failures being retried. An optimistic conflict means 문장 단위 재시도는 바로 재시도하려는 실패에 틀린 답이다. 낙관적 충돌은 시도가 계산의 바탕으로 삼은 상태가 더는 커밋된
the state the attempt computed against is no longer the committed state; re-issuing the same 상태가 아니라는 뜻이다. 같은 문장을 다시 내면 이미 움직인 version에 대고 같은 틀린 답을 계산한다. 도메인 규칙은 다시 읽은
statement computes the same wrong answer against a version that has moved on. The domain rules have 데이터 위에서 다시 돌아야 하고, 그것은 유스케이스 전체라는 뜻이다.
to run again over reloaded data, which means the whole use case.
Reusing the Persistence Context would be equally wrong: the second attempt would read the first Persistence Context를 다시 쓰는 것도 똑같이 틀렸다: 두 번째 시도가 1차 cache에서 첫 시도의 낡은 엔티티를 읽게 된다. 그리고
attempt's stale entities out of the first-level cache. And with the advice ordering inverted, the advice 순서가 뒤집히면 재시도 반복문이 이미 rollback-only로 표시된 트랜잭션 하나 안에서 돌아서, 두 번째 시도가 아무것도
retry loop would run inside one transaction that has already been marked rollback-only, so the 실행하지 않고 바로 실패한다.
second attempt fails immediately without executing anything.
The cost is that a retryable use case must be safe to run from scratch — no irreversible external 비용은 재시도할 수 있는 유스케이스가 처음부터 돌려도 안전해야 한다는 것이다 — 커밋 전에 되돌릴 수 없는 외부 효과가 없어야
effect before the commit. `IrreversibleSideEffectContext` lets a use case declare when that does not 한다. `IrreversibleSideEffectContext`로 유스케이스가 그렇지 않을 때를 선언할 수 있고, 그러면 정책은 남은 예산이 얼마든 그
hold, and the policy then refuses to retry it whatever budget remains. 재시도를 거절한다.
## Enforcement ## 강제
`FullTransactionRetryCoordinatorTest`; `RetryableJpaTransactionInterceptor.DEFAULT_ORDER`. `FullTransactionRetryCoordinatorTest`, `RetryableJpaTransactionInterceptor.DEFAULT_ORDER`.
+32 -40
View File
@@ -7,57 +7,49 @@
- 현재 정본: `docs/jpa/transaction-guide.md` - 현재 정본: `docs/jpa/transaction-guide.md`
<!-- 머리 블록 끝 --> <!-- 머리 블록 끝 -->
# ADR-JPA-003 — Completion unknown is never retried # ADR-JPA-003 — 완료를 모름은 절대 재시도하지 않는다
- Status: Accepted; amended 2026-09-25 — `TransactionCompletionResolver`, `CommitFailureClassifier` - 상태: 채택. 2026-09-25 보완 — `TransactionCompletionResolver`, `CommitFailureClassifier`, 재시도 엔진을 지웠다. 유일한
and the retry engine were removed. The invariant holds because `SpringTransactionPort`, the only 트랜잭션 엔진인 `SpringTransactionPort`가 아무것도 재시도하지 않으므로 불변식이 지켜진다. 아래 강제 절도 그에 맞게
transaction engine, retries nothing; enforcement below is updated accordingly. 고쳤다.
- Date: 2026-08-11 - 날짜: 2026-08-11
- Design: §17 - 설계: §17
## Context ## 배경
A connection can break while a commit is in flight. The server may have committed; the 커밋이 진행 중일 때 연결이 끊길 수 있다. 서버가 커밋했을 수도 있고, 확인 응답만 잃었을 수도 있다. driver는 둘을 구별하지
acknowledgement may simply have been lost. The driver cannot tell the two apart. 못한다.
## Decision ## 결정
`TransactionCompletionUnknownException` is never retried, automatically or otherwise. It is `TransactionCompletionUnknownException`은 자동이든 아니든 절대 재시도하지 않는다. 트랜잭션 단계가 `COMMITTING`인 동안 본
produced only by a failure observed while the transaction phase is `COMMITTING`, and only for 실패에서만, 그리고 SQLSTATE `40003`, 연결 class(`08*`) 상태, 전송 끊김에 대해서만 만든다. 회복은 도메인별 맞춰 보기다.
SQLSTATE `40003`, a connection-class (`08*`) state, or a transport break. Recovery is
domain-specific reconciliation.
## Consequences ## 결과
Retrying a possibly-committed write is the most damaging thing this platform could do: a duplicate 커밋됐을지 모르는 쓰기를 재시도하는 것이 이 플랫폼이 할 수 있는 가장 해로운 일이다: 중복 결제, 중복 주문, 두 번 깎기.
payment, a duplicate order, a double decrement. There is no budget or backoff that makes it safe, 실패가 일시적인 것이 아니라 알 수 없는 것이라서, 그것을 안전하게 만드는 예산이나 backoff는 없다.
because the failure is epistemic rather than transient.
The invariant is enforced at the type level rather than by policy alone. `JpaFailureContext` refuses 불변식은 정책만이 아니라 타입 수준에서 강제한다. `JpaFailureContext`는 재시도할 수 있는 completion-unknown 문맥을 만들기를
to construct a retryable completion-unknown context, and the exception rebuilds its context through 거절하고, 예외는 무엇을 받든 안전한 factory로 자기 문맥을 다시 만든다. 그래서 나중의 정책 결함이 안전하지 않은 재시도를 낳을
the safe factory whatever it is handed. A future policy bug therefore cannot produce an unsafe 수 없다 — 그것에 필요한 값이 존재하지 않는다.
retry — the value it would need does not exist.
The rule is deliberately narrow in the other direction too. Classifying every connection failure as 규칙은 반대 방향으로도 일부러 좁다. 모든 연결 실패를 completion-unknown으로 분류하면 보통의 pool 고갈과 서버 재시작이 맞춰
completion-unknown would push ordinary pool exhaustion and server restarts into the reconciliation 보기 queue로 밀려 들어가고, 그것은 운영자에게 그 queue를 읽지 않고 비우도록 길들인다 — 그러면 중요했던 항목 하나가 나머지와
queue, which trains operators to clear that queue without reading it — and then the one entry that 함께 지워진다.
mattered gets cleared with the rest.
The cost is that the domain must supply the resolver. The platform cannot: only the domain knows 비용은 도메인이 resolver를 줘야 한다는 것이다. 플랫폼은 할 수 없다: 어떤 멱등성 레코드, 업무 행, outbox 항목이 쓰기가
which idempotency record, business row, or outbox entry proves the write happened. 일어났음을 증명하는지는 도메인만 안다.
## Enforcement ## 강제
Production path: `SpringTransaction` records when the action has returned in a write transaction it 운영 경로: `SpringTransaction`은 자기가 시작한 쓰기 트랜잭션에서 action이 돌아온 때를 기록한다. 그 뒤의 실패는
began; a failure after that point goes through `PersistenceExceptionTranslator#translateCommitFailure`를 거치고, 그것이 `08*`, `40003`, vendor 종료 상태
`PersistenceExceptionTranslator#translateCommitFailure`, which builds this exception for `08*`, (`SqlStateErrorMapping#commitOutcomeUnknownStates`, PostgreSQL `57P01`/`57P02`), 전송 끊김에 대해 이 예외를 만든다. 커밋 안의
`40003`, a vendor termination state (`SqlStateErrorMapping#commitOutcomeUnknownStates`, PostgreSQL Hibernate flush는 COMMIT 자체와 나뉘지 않으므로, 그 flush 중에 잃은 연결도 모름으로 알린다 — 안전한 쪽이다. review
`57P01`/`57P02`) or a transport break. Hibernate's flush inside the commit is not separated from the 04-01(2026-11-01) 전까지는 아무것도 이 예외를 만들지 않았고, 커밋 단계의 `08*`가 재시도할 수 있는 `DB_UNAVAILABLE`로 호출자에게
COMMIT itself, so a connection lost during that flush is also reported as unknown — the safe side. 닿았다.
Until review 04-01 (2026-11-01) nothing constructed the exception and a commit-phase `08*` reached
callers as the retryable `DB_UNAVAILABLE`.
`JpaFailureContextTest`; `SpringTransactionTest`; `PersistenceExceptionTranslatorTest`; `JpaFailureContextTest`, `SpringTransactionTest`, `PersistenceExceptionTranslatorTest`,
`PostgreSqlTransactionIntegrationTest#connectionLossDuringCommitSurfacesAsCompletionUnknownAndIsNeverRetried` `PostgreSqlTransactionIntegrationTest#connectionLossDuringCommitSurfacesAsCompletionUnknownAndIsNeverRetried`
(asserts `DB_COMPLETION_UNKNOWN`; also the `jpa-failure` lane, i.e. release gate (`DB_COMPLETION_UNKNOWN`을 단언한다. `jpa-failure` lane, 곧 릴리스 gate `completion-unknown-no-retry`이기도 하다).
`completion-unknown-no-retry`).
@@ -7,41 +7,37 @@
- 현재 정본: `docs/jpa/migration-guide.md` - 현재 정본: `docs/jpa/migration-guide.md`
<!-- 머리 블록 끝 --> <!-- 머리 블록 끝 -->
# ADR-JPA-004 — Flyway is the schema source of truth # ADR-JPA-004 — schema의 정본은 Flyway다
- Status: Accepted - 상태: 채택
- Date: 2026-08-11 - 날짜: 2026-08-11
- Design: §31 - 설계: §31
## Context ## 배경
Hibernate can create and alter schema from the entity mapping. Flyway can apply versioned scripts. Hibernate는 엔티티 대응에서 schema를 만들고 바꿀 수 있다. Flyway는 버전 있는 script를 적용할 수 있다. 둘이 함께 schema를 가질
Both cannot own the schema. 수는 없다.
## Decision ## 결정
Flyway owns every schema change. Hibernate validates and never mutates: `ddl-auto` is `validate` or 모든 schema 변경은 Flyway가 가진다. Hibernate는 검증만 하고 절대 바꾸지 않는다: `ddl-auto`는 `validate`나 `none`이고, 기동 때
`none`, enforced at startup. The runtime database credential holds no DDL privilege, so the rule is 강제한다. 런타임 데이터베이스 credential에는 DDL 권한이 없으므로, 규칙을 설정만이 아니라 서버도 강제한다.
enforced by the server as well as by configuration.
## Consequences ## 결과
`ddl-auto=update` fails in a specific and expensive way: it adds but never drops or narrows, so the `ddl-auto=update`는 구체적이고 비싸게 실패한다: 더하기만 하고 지우거나 좁히지 않아서, 결과는 이전 것도 대응이 설명하는 것도
result is a schema that is neither the previous one nor the one the mappings describe — produced 아닌 schema다 — 먼저 시작한 인스턴스가 무엇을 했는지 기록도 없이 소리 없이 만든다.
silently, by whichever instance started first, with no record of what it did.
Two credentials rather than one is what makes this more than a convention. A configuration rule can credential을 하나가 아니라 둘 두는 것이 이것을 관례 이상으로 만든다. 설정 규칙은 속성 하나로 덮을 수 있다. `CREATE`가 없는
be overridden by a property; a role without `CREATE` cannot be overridden by anything the role은 애플리케이션이 무엇을 하든 덮을 수 없다.
application does.
Validation fails closed and never repairs. `repair` rewrites the schema history to match the scripts 검증은 실패하면 닫히고 절대 고치지 않는다. `repair`는 schema 이력을 디스크의 script에 맞게 다시 쓰는데, 그것은 어떤 변경이
on disk, which resolves a checksum mismatch by deleting the evidence of which change is missing. 빠졌는지의 증거를 지워서 checksum 불일치를 푸는 것이다.
The cost is that a schema change requires a migration script and a deployment step. That is the 비용은 schema 변경에 migration script와 배포 단계가 필요하다는 것이다. 그것이 의도한 비용이다: schema 변경을 리뷰할 수 있고
intended cost: it makes schema change reviewable and reversible. 되돌릴 수 있게 만든다.
## Enforcement ## 강제
`JpaDangerousConfigurationGuard`; `FlywaySchemaPolicy`; `FlywayValidationGate` (testkit, used by the `JpaDangerousConfigurationGuard`, `FlywaySchemaPolicy`, `FlywayValidationGate`(testkit, migration 계약 시험이 쓴다),
migration contract tests); `PostgreSqlRuntimeRoleVerifier`; release gates `flyway-validate` and `PostgreSqlRuntimeRoleVerifier`, 릴리스 gate `flyway-validate`와 `runtime-role-no-ddl`.
`runtime-role-no-ddl`.
@@ -7,41 +7,36 @@
- 현재 정본: `docs/jpa/support-matrix.md` - 현재 정본: `docs/jpa/support-matrix.md`
<!-- 머리 블록 끝 --> <!-- 머리 블록 끝 -->
# ADR-JPA-005 — Contracts run against real PostgreSQL # ADR-JPA-005 — 계약은 실제 PostgreSQL에 대고 돈다
- Status: Accepted - 상태: 채택
- Date: 2026-08-11 - 날짜: 2026-08-11
- Design: §40 - 설계: §40
## Context ## 배경
An in-memory database makes tests fast and hermetic. A container makes them slow and requires 메모리 데이터베이스는 시험을 빠르고 밀폐되게 만든다. container는 느리게 만들고 Docker를 요구한다.
Docker.
## Decision ## 결정
Every persistence contract runs against real PostgreSQL 16, 17, and 18 in containers. H2 remains a 모든 영속 계약은 container 안의 실제 PostgreSQL 16, 17, 18에 대고 돈다. H2는 로컬 개발 편의로 남고 어떤 계약도 만족시키지
local-development convenience and never satisfies a contract. The lanes fail closed when Docker is 않는다. Docker가 없으면 lane은 건너뛰지 않고 실패하면 닫힌다.
absent rather than skipping.
## Consequences ## 결과
The behaviours these contracts verify either do not exist in H2 or differ there: SQLSTATE values for 이 계약이 검증하는 동작은 H2에 없거나 다르다: 같은 위반의 SQLSTATE 값, `FOR UPDATE SKIP LOCKED`의 뜻, JSONB 연산자, 범위 타입,
the same violation, `FOR UPDATE SKIP LOCKED` semantics, JSONB operators, range types, concurrent concurrent index 만들기, `search_path` 권한, page를 나눈 컬렉션 fetch의 생성 SQL. H2 실행이 초록이면 코드가 컴파일되고 돈다는
index builds, `search_path` privileges, and the generated SQL for a paged collection fetch. A green 증거이지 — 위 어느 것이 지켜진다는 증거가 아니다.
H2 run is evidence that the code compiles and runs — not that any of the above holds.
Three versions rather than one because the platform claims three. A contract suite that ran only on 버전을 하나가 아니라 셋 두는 것은 플랫폼이 셋을 주장하기 때문이다. 16에서만 도는 계약 suite는 「17과 18에서 Stable」을 가정으로
16 would make "Stable on 17 and 18" an assumption. 만든다.
Skipping on missing Docker is the failure mode this decision most wants to avoid: a skipped contract Docker가 없을 때 건너뛰는 것이 이 결정이 가장 피하려는 실패 방식이다: 건너뛴 계약은 성공을 알리고, CI는 결국 그 침묵을
reports success, and CI eventually inherits that silence. `PostgreSqlContainerFactory.assertDockerAvailable()` 물려받는다. `PostgreSqlContainerFactory.assertDockerAvailable()`은 대신 던진다.
throws instead.
The cost is that the contract lanes need Docker and take minutes. The unit lane stays hermetic and 비용은 계약 lane에 Docker가 필요하고 몇 분이 걸린다는 것이다. 단위 lane은 밀폐되고 빠른 채로 남고 대부분의 시험이 거기 있다.
fast, and is where most tests live; the container lanes verify the things only a real server can container lane은 실제 서버만 답할 수 있는 것을 검증한다.
answer.
## Enforcement ## 강제
`PostgreSqlVersion.stable()`; `PostgreSqlContainerFactory`; release gate `postgresql-contract`. `PostgreSqlVersion.stable()`, `PostgreSqlContainerFactory`, 릴리스 gate `postgresql-contract`.
@@ -7,68 +7,58 @@
- 현재 정본: `docs/jpa/repository-adaptation.md` - 현재 정본: `docs/jpa/repository-adaptation.md`
<!-- 머리 블록 끝 --> <!-- 머리 블록 끝 -->
# ADR-JPA-006 — `audit` is the sole technical audit model # ADR-JPA-006 — 기술 감사 모델은 `audit` 하나뿐이다
- Status: Accepted - 상태: 채택
- Date: 2026-08-24 - 날짜: 2026-08-24
- Review: `docs/reviews/2026-08-14-jpa-module-code-review.md` JPA-022 - 리뷰: `docs/reviews/2026-08-14-jpa-module-code-review.md` JPA-022
## Context ## 배경
Two complete technical-audit mechanisms live in this leaf and they disagree about the schema. 이 leaf에 완전한 기술 감사 장치가 둘 있고, 둘은 schema에 대해 의견이 다르다.
`audit/AuditableEntity` stamps `created_at`/`created_by`/`updated_at`/`updated_by` with an actor `audit/AuditableEntity`는 길이 256의 actor 열과 함께 `created_at`/`created_by`/`updated_at`/`updated_by`를 넣고, 명시적인
column of length 256, captured through explicit `initializeAudit`/`applyModification` calls and an `initializeAudit`/`applyModification` 호출과 `AuditContextPort`로 값을 잡는다. `auditing/AuditMetadata`는 길이 64의 actor 열과
`AuditContextPort`. `auditing/AuditMetadata` is a Spring Data embeddable that stamps 함께 `created_*`/`modified_*`를 넣는 Spring Data embeddable이고, `AuditorAware`를 거쳐 `@CreatedDate` 같은 것으로 값을 잡는다.
`created_*`/`modified_*` with an actor column of length 64, captured by `@CreatedDate` and friends
through an `AuditorAware`.
Only the first is real: it is what the sample entities extend and what the migrations were written 실제로 쓰이는 것은 첫째뿐이다: 샘플 엔티티가 상속하는 것이고 migration도 그것을 위해 썼다. `JpaAuditingConfiguration`은 Spring
for. `JpaAuditingConfiguration` is not a Spring `@Configuration`, and nothing in production `@Configuration`이 아니고, 운영 코드의 어떤 것도 `auditing` 타입 셋 중 하나를 만들지 않는다.
constructs any of the three `auditing` types.
The review asked for one canonical model with a migration or activation decision. The failure mode 리뷰는 migration이나 켜기 결정이 붙은 정해진 모델 하나를 요구했다. 막으려던 실패 방식은 구체적이다: 새 엔티티를 쓰는 사람이
it was protecting against is specific: an author of a new entity picks whichever package they find 먼저 찾은 패키지를 고르고, 그러면 열 이름, actor 길이, 값 잡는 lifecycle이 테이블마다 갈라진다.
first, and column names, actor lengths and capture lifecycles then diverge per table.
## Decision ## 결정
`audit/AuditableEntity` is canonical and the unused `auditing/*` implementation is removed. `audit/AuditableEntity`가 정본이고, 쓰지 않는 `auditing/*` 구현은 지운다.
Keeping a complete, incompatible implementation as a dormant candidate created exactly the 완전하고 호환되지 않는 구현을 잠든 후보로 두는 것이 바로 리뷰가 경고한 모호함을 만들었다: 새 엔티티가 자동 완성으로 패키지를
ambiguity the review warned about: a new entity could choose a package by autocomplete and silently 고르고 열 이름, actor 한계, 값 잡는 lifecycle을 소리 없이 바꿀 수 있었다. 나중에 Spring Data auditing으로 옮기는 것은 정본
change column names, actor bounds and capture lifecycle. A future move to Spring Data auditing is a 모델의 migration이지, 옆에서 어긋나 온 두 번째 모델을 켜는 것이 아니다.
migration of the canonical model, not activation of a second model that has drifted beside it.
That future migration must preserve `created_*`/`updated_*`, the 256-character actor contract, 그 나중의 migration은 `created_*`/`updated_*`, 256자 actor 계약, `AuditContextPort`, 공용 `Clock`을 지켜야 한다. listener 배선과
`AuditContextPort`, and the shared `Clock`; listener wiring and entity conversion land atomically. 엔티티 변환은 한 번에 들어온다.
## Consequences ## 결과
Two audit mechanisms remain readable in one leaf, and a reader has to be told which one is live. 감사 장치 둘이 한 leaf 안에 읽을 수 있게 남고, 읽는 사람에게 어느 것이 살아 있는지 알려야 한다. 그 비용은 이 문서, 패키지
That cost is paid in this document, in the package javadoc and in a test whose name says so. javadoc, 그리고 이름이 그것을 말하는 시험이 낸다.
Two failure modes stay silent unless they are asserted, so both are: 단언하지 않으면 소리 없이 남는 실패 방식이 둘 있으므로, 둘 다 단언한다:
- The candidate acquires a stereotype and starts stamping in every deployment that has this module - 후보가 stereotype을 얻어 이 모듈이 classpath에 있는 모든 배포에서 값을 넣기 시작한다. 테이블에 `modified_*` 열이 없는 배포도
on the classpath, including the ones whose tables have no `modified_*` columns — where the result 포함된다 — 거기서 결과는 기능이 아니라 기동 실패다.
is a failed startup rather than a feature. - 누가 한쪽 열 이름을 고쳐 둘을 「맞춘다」. 그러면 배포된 테이블이 migration된 schema와 그 엔티티가 기대하는 schema가 둘 사이
- Somebody "harmonises" the two by editing one side's column names, at which point the schema a migration 없이 갈라진다.
deployed table was migrated for and the schema its entity expects diverge with no migration
between them.
If the candidate is ever promoted, it is promoted atomically: forward migration, sample conversion, 후보를 언젠가 승격하면 한 번에 승격한다: 앞으로 가는 migration, 샘플 변환, `AuditContextPort → AuditorAware`와
`AuditContextPort → AuditorAware` and `Clock → DateTimeProvider` bridges land together, and this `Clock → DateTimeProvider` 다리가 함께 들어오고, 이 ADR은 보완이 아니라 대체된다.
ADR is superseded rather than amended.
Bulk and native updates stamp nothing under either mechanism. That is a property of JPA, not of the bulk·native update는 어느 장치에서든 아무것도 넣지 않는다. 그것은 여기서 고른 것의 성질이 아니라 JPA의 성질이므로, 없다고
choice made here, so it is enforced separately rather than assumed away. 치지 않고 따로 강제한다.
## Enforcement ## 강제
`JpaAuditMechanismRule.entitiesUseExactlyOneAuditMechanism` and `JpaAuditMechanismRule.entitiesUseExactlyOneAuditMechanism`과 `bulkUpdatesOfAuditedEntitiesStampAudit`를 조립 루트의
`bulkUpdatesOfAuditedEntitiesStampAudit`, run against the real production graph by `JpaProductionArchitectureTest`가 실제 운영 그래프에 대고 돌린다 — fixture가 아니다. 이 규칙 묶음의 앞 버전은 fixture에 대고
`JpaProductionArchitectureTest` at the composition root — not against fixtures, which is how the 돌아서 아무것에도 적용되지 않은 채 통과했다. `AuditingCandidateStatusTest`가 후보에 조립하는 stereotype이 없고 두 열 집합이
earlier version of this rule pack passed while applying to nothing. `AuditingCandidateStatusTest` 따로 남는다고 단언한다. `JpaAuditMechanismRuleTest`가 규칙 자신의 부정 경우를 시험한다.
asserts the candidate carries no composing stereotype and that the two column sets stay distinct.
`JpaAuditMechanismRuleTest` exercises the rules' own negative cases.
+39 -46
View File
@@ -7,66 +7,59 @@
- 현재 정본: `docs/mongodb/repository-adaptation.md` - 현재 정본: `docs/mongodb/repository-adaptation.md`
<!-- 머리 블록 끝 --> <!-- 머리 블록 끝 -->
# ADR-MONGO-001 — MongoDB platform boundary # ADR-MONGO-001 — MongoDB 플랫폼 경계
- **Status:** Accepted - **상태:** 채택
- **Date:** 2026-08-13 - **날짜:** 2026-08-13
- **Design source:** `docs/superpowers/specs/2026-08-11-mongodb-document-persistence-platform-design.md` §1, §2 (D-01, D-04, D-05), §5, §6 - **설계 출처:** `docs/superpowers/specs/2026-08-11-mongodb-document-persistence-platform-design.md` §1, §2 (D-01, D-04, D-05), §5, §6
## Context ## 배경
Two failure modes are common when a team wraps MongoDB. 팀이 MongoDB를 감쌀 때 흔한 실패 방식이 둘 있다.
The first is flattening: a shared `CommonMongoRepository<T, ID>` and a generic CRUD facade, which 첫째는 납작하게 만들기다: 공용 `CommonMongoRepository<T, ID>`와 범용 CRUD 창구. 모든 collection이 id 전략, 일관성 profile,
forces every collection to share an id strategy, a consistency profile and a query surface. MongoDB's query surface를 같이 쓰게 강요한다. MongoDB의 단일 문서 원자성, aggregation 모델, change stream에 더는 닿을 수 없고, 다른 것이
single-document atomicity, aggregation model and change streams stop being reachable, and the first 필요한 첫 collection은 cast나 새는 제네릭을 받는다.
collection that needs something different gets a cast or a leaky generic.
The second is unrestricted exposure: the driver and `runCommand` available everywhere. Then any 둘째는 제한 없는 노출이다: driver와 `runCommand`를 어디서나 쓸 수 있다. 그러면 어느 서비스든 요청 스레드에서 collection을
service can drop a collection, run an unbounded pipeline, or issue an admin command from a request 지우거나, 한계 없는 pipeline을 돌리거나, admin 명령을 낼 수 있고, 구조로 잡을 것이 없으니 어떤 리뷰도 잡지 못한다.
thread, and no review catches it because there is nothing structural to catch.
## Decision ## 결정
The domain owns its documents; the platform owns the cross-cutting decisions. Four exposure planes: 도메인이 자기 문서를 가지고, 플랫폼이 가로지르는 결정을 가진다. 노출 plane 넷:
| Plane | Contents | Client | | plane | 내용 | client |
|---|---|---| |---|---|---|
| D1 Standard document persistence | Spring Data repositories, typed queries, mapping manifest, atomic update primitives, optimistic revision | Stable API V1, `apiStrict=true` | | D1 표준 문서 영속 | Spring Data repository, 타입 있는 query, 대응 manifest, 원자 update 기본 장치, 낙관적 revision | Stable API V1, `apiStrict=true` |
| D2 Advanced document operations | `MongoTemplate`, transactions/sessions, bulk, aggregation, keyset cursors, change streams | Stable API V1, `apiStrict=true` | | D2 고급 문서 연산 | `MongoTemplate`, 트랜잭션·세션, bulk, aggregation, keyset cursor, change stream | Stable API V1, `apiStrict=true` |
| D3 Explicit Mongo capability | Native BSON, time series, search/vector, CSFLE/QE, shard-aware operations | Separate capability client | | D3 명시적 Mongo capability | native BSON, time series, search·vector, CSFLE·QE, shard를 아는 연산 | 따로 둔 capability client |
| D4 Admin plane | Collection, validator, index, migration, shard, repair | Separate admin client and credential | | D4 admin plane | collection, validator, index, migration, shard, repair | 따로 둔 admin client와 credential |
Specifically: 구체적으로:
1. **No `CommonMongoRepository<T, ID>`.** Each aggregate declares its own repository. 1. **`CommonMongoRepository<T, ID>`가 없다.** aggregate마다 자기 repository를 선언한다.
2. **D1/D2 run on Stable API V1 with `apiStrict=true`,** so a command outside the versioned API fails 2. **D1·D2는 `apiStrict=true`인 Stable API V1에서 돈다.** 그래서 버전 있는 API 밖의 명령은 다음 서버 업그레이드 때가 아니라
at development time instead of on the next server upgrade. 개발 때 실패한다.
3. **D3 is not a raw-client escape.** Every call passes a fixed admission order: capability registered 3. **D3는 raw client로 빠져나가는 길이 아니다.** 모든 호출이 정해진 허가 순서를 지난다: capability 등록 → 데이터베이스
→ database profile → collection allowlist → operation name → timeout → consistency profile → profile → collection 허용 목록 → operation 이름 → timeout → 일관성 profile → 결과 한계 → trace → 가리기 → 명령 category →
result limit → trace → redaction → command category → admin-command refusal → execute. admin 명령 거절 → 실행.
4. **D4 is a separate client with a separate credential.** No application-plane path reaches it; 4. **D4는 따로 둔 credential을 가진 따로 둔 client다.** 애플리케이션 plane 경로는 그것에 닿지 않는다.
`PolicyAwareMongoNativeGateway` refuses admin-category commands regardless of capability. `PolicyAwareMongoNativeGateway`는 capability와 관계없이 admin category 명령을 거절한다.
5. **Advanced and Experimental capabilities are opt-in modules**, never transitive dependencies of the 5. **Advanced와 Experimental capability는 골라 쓰는 모듈이고**, Stable surface의 전이 의존이 되지 않는다.
Stable surface.
## Consequences ## 결과
**Positive.** MongoDB's semantics stay reachable. Misuse is refused structurally rather than reviewed **좋은 점.** MongoDB의 뜻에 계속 닿을 수 있다. 잘못된 사용은 리뷰로 찾지 않고 구조로 거절한다. 서버 업그레이드가 D1·D2
for. A server upgrade cannot silently change D1/D2 behaviour. Admin operations have their own audit 동작을 소리 없이 바꿀 수 없다. admin 연산은 자기 감사 흔적과 credential을 가진다.
trail and credential.
**Negative.** Every operation needs a registered name and profile, so a new query is a small amount of **나쁜 점.** 모든 operation에 등록된 이름과 profile이 필요해서, 새 query에는 0이 아니라 약간의 설정이 든다. 정말 새 capability는
configuration rather than zero. A genuinely new capability requires a registration before it can be 쓰기 전에 등록이 필요하다. 둘 다 일부러다: 비용은 operation마다 한 번, 리뷰 때 낸다.
used. Both are deliberate: the cost is paid once per operation, at review time.
**Rejected alternative — "expose the driver, rely on code review."** Review does not scale to every **버린 대안 — 「driver를 내놓고 코드 리뷰에 기댄다」.** 리뷰는 모든 서비스의 모든 query로 늘어나지 못하고, 중요한 연산
query in every service, and the operations that matter (unbounded pipeline, `dropCollection`, (한계 없는 pipeline, `dropCollection`, 사용자 입력에 대한 anchor 없는 정규식)은 diff에서 눈에 띄지 않는다.
unanchored regex on user input) look unremarkable in a diff.
## Repository adaptation ## 저장소에 맞추기
The design assumes 19 Gradle modules under `modules/mongodb/`. This repository's fail-closed registry 설계는 `modules/mongodb/` 아래 Gradle 모듈 19개를 가정한다. 이 저장소의 실패하면 닫히는 registry는 정확히 19개의 leaf identity를
declares exactly 19 leaf identities, so the modules became package boundaries inside 선언하므로, 그 모듈들은 `:adapter:outbound:persistence-mongo` 안의 패키지 경계가 됐고 ArchUnit이 강제한다.
`:adapter:outbound:persistence-mongo`, enforced by ArchUnit. See [docs/mongodb/repository-adaptation.md](../mongodb/repository-adaptation.md)를 본다.
[docs/mongodb/repository-adaptation.md](../mongodb/repository-adaptation.md).
+36 -44
View File
@@ -7,61 +7,53 @@
- 현재 정본: `docs/mongodb/bson-mapping-guide.md` - 현재 정본: `docs/mongodb/bson-mapping-guide.md`
<!-- 머리 블록 끝 --> <!-- 머리 블록 끝 -->
# ADR-MONGO-002 — BSON representation is a pinned manifest # ADR-MONGO-002 — BSON 표현은 고정한 manifest다
- **Status:** Accepted - **상태:** 채택
- **Date:** 2026-08-13 - **날짜:** 2026-08-13
- **Design source:** design §10, decision D-06 - **설계 출처:** 설계 §10, 결정 D-06
## Context ## 배경
How a Java value is represented in BSON is a data contract, but nothing in the default toolchain Java 값을 BSON으로 어떻게 나타내는지는 데이터 계약인데, 기본 toolchain의 어떤 것도 그것을 계약으로 다루지 않는다. Spring Data와
treats it as one. Spring Data and the MongoDB driver both have defaults, and those defaults have MongoDB driver에는 둘 다 기본값이 있고, 그 기본값은 버전마다 바뀌어 왔다. `BigDecimal`은 `Double`, `String`, `Decimal128` 중
changed across versions. A `BigDecimal` can land as a `Double`, a `String` or a `Decimal128`; a `UUID` 무엇으로든 들어갈 수 있다. `UUID`는 `Binary` subtype 3이나 subtype 4로 들어갈 수 있다. `Instant`는 `Date`나 `String`으로 들어갈
can land as `Binary` subtype 3 or subtype 4; an `Instant` can land as a `Date` or a `String`. 수 있다.
The consequences are asymmetric. A representation change is invisible in a value-equality test — 결과는 비대칭이다. 표현이 바뀌어도 값 동등 시험에는 보이지 않는다 — `12.30`은 double이든 `Decimal128`이든 `12.30`처럼 보인다 —
`12.30` looks like `12.30` whether it is a double or a `Decimal128` — but once a collection holds 하지만 collection에 운영 데이터가 들면 그것을 바꾸는 것은 전체 migration이다. 그리고 UUID 경우는 migration보다 나쁘다: 옛 Java
production data, changing it is a full migration. And the UUID case is worse than a migration: legacy 표현은 UUID의 두 절반을 byte-swap하므로, 한 표현으로 쓰고 다른 표현으로 읽은 문서는 *다르지만 유효해 보이는* UUID를 낸다.
Java representation byte-swaps two halves of the UUID, so a document written under one representation 오류는 없다. 엉뚱한 레코드를 받는다.
and read under the other yields a *different, valid-looking* UUID. Nothing errors. You get the wrong
record.
## Decision ## 결정
`MongoTypeRepresentationManifest` pins the representation for every type the platform maps, and `MongoTypeRepresentationManifest`가 플랫폼이 대응시키는 모든 타입의 표현을 고정하고, `MongoMappingConfiguration`이 그것으로
`MongoMappingConfiguration` builds the Spring Data converters from it. Nothing relies on a library Spring Data converter를 만든다. 라이브러리 기본값에 기대는 것은 없다.
default.
| Java | BSON | Rationale | | Java | BSON | 근거 |
|---|---|---| |---|---|---|
| `UUID` | `Binary` subtype 4 (`STANDARD`) | Subtype 3 byte-swaps; cross-representation reads are silently wrong. | | `UUID` | `Binary` subtype 4(`STANDARD`) | subtype 3은 byte-swap한다. 표현을 넘나드는 읽기는 소리 없이 틀린다. |
| `BigDecimal` | `Decimal128` | A double cannot represent `12.30`; money compared as a double is eventually wrong by a cent. | | `BigDecimal` | `Decimal128` | double은 `12.30`을 나타내지 못한다. double로 비교한 돈은 결국 1원씩 틀린다. |
| `BigInteger` | `Decimal128`, or declared `String` when out of range | 34 significant digits; out of range fails on write instead of rounding. | | `BigInteger` | `Decimal128`, 범위를 넘으면 선언한 `String` | 유효 숫자 34자리. 범위를 넘으면 반올림하지 않고 쓰기에서 실패한다. |
| `Instant` / `OffsetDateTime` / `ZonedDateTime` | UTC `Date` | One instant, one representation. | | `Instant` / `OffsetDateTime` / `ZonedDateTime` | UTC `Date` | 시각 하나, 표현 하나. |
| `LocalDate` | declared per field | A calendar day is not an instant. | | `LocalDate` | 필드마다 선언 | 달력의 날은 시각이 아니다. |
| `LocalDateTime` | **refused** | No offset: the stored value depends on the writing JVM's default zone. | | `LocalDateTime` | **거절** | offset이 없다: 저장 값이 쓰는 JVM의 기본 시간대에 따라 달라진다. |
| `enum` | `String` name | Ordinals renumber when someone inserts a constant. | | `enum` | `String` 이름 | 누가 상수를 끼워 넣으면 ordinal이 다시 매겨진다. |
Type metadata follows `MongoTypeMetadataPolicy` — `NONE`, `ALIAS` or `CLASS_NAME`. A 타입 metadata는 `MongoTypeMetadataPolicy` — `NONE`, `ALIAS`, `CLASS_NAME` — 를 따른다. `@LongLivedMongoDocument` 타입은
`@LongLivedMongoDocument` type may not use `CLASS_NAME`: writing a FQCN into a million documents makes `CLASS_NAME`을 쓰면 안 된다: 문서 백만 개에 FQCN을 쓰면 패키지 이름 바꾸기가 데이터 migration이 된다.
a package rename a data migration.
The manifest is enforced by a golden gate. `MongoBsonSnapshot` canonicalises a stored document, manifest는 golden gate가 강제한다. `MongoBsonSnapshot`이 저장된 문서를 정규화하면서 BSON 타입을 지키고 없음과 null을 구별해
preserving BSON types and keeping missing distinct from null, and 두며, `MongoBsonSnapshotAssert.hasTypeSignature(...)`가 표현이 바뀌면 실패한다. registry는 기본값을 물려받지 않고
`MongoBsonSnapshotAssert.hasTypeSignature(...)` fails on any representation change. The registry `UuidCodec(STANDARD)`를 명시해 고정한다. 기본값을 물려받는 것이 바로 gate가 잡으려는 어긋남이기 때문이다.
pins `UuidCodec(STANDARD)` explicitly rather than inheriting a default, since inheriting the default
is the exact drift the gate exists to catch.
## Consequences ## 결과
**Positive.** A library upgrade cannot move a representation without failing a test. Money is exact. **좋은 점.** 라이브러리 업그레이드가 시험을 실패시키지 않고 표현을 옮길 수 없다. 돈이 정확하다. UUID가 자기 자신으로 다시
UUIDs read back as themselves. Class moves stay refactors. 읽힌다. 클래스 옮기기는 리팩터링으로 남는다.
**Negative.** Every representation-affecting change requires updating a snapshot *and* writing a **나쁜 점.** 표현에 영향을 주는 모든 변경에 snapshot 갱신 *그리고* migration 작성이 필요하다. 새로 대응시키는 타입은 쓰기 전에
migration. A new mapped type needs a manifest entry before it can be used. This is the intended manifest 항목이 필요하다. 의도한 마찰이다: 대안은 운영에서 변경을 발견하는 것이다.
friction: the alternative is discovering the change in production.
**Rejected alternative — "snapshot the JSON."** JSON destroys exactly the distinctions the gate **버린 대안 — 「JSON을 snapshot한다」.** JSON은 gate가 지키는 바로 그 구별을 없앤다: `Decimal128`과 `String`은 둘 다 글로
protects: `Decimal128` and `String` both render as text, `Binary` UUID and `ObjectId` both render as 나오고, `Binary` UUID와 `ObjectId`는 둘 다 hex로 나오며, 없음과 null은 둘 다 사라진다.
hex, and missing and null both disappear.
+35 -43
View File
@@ -7,33 +7,29 @@
- 현재 정본: `docs/mongodb/consistency-transaction-guide.md` - 현재 정본: `docs/mongodb/consistency-transaction-guide.md`
<!-- 머리 블록 끝 --> <!-- 머리 블록 끝 -->
# ADR-MONGO-003 — Transaction body retry and commit retry are separate loops # ADR-MONGO-003 — 트랜잭션 본문 재시도와 커밋 재시도는 따로 도는 반복문이다
- **Status:** Accepted - **상태:** 채택
- **Date:** 2026-08-13 - **날짜:** 2026-08-13
- **Design source:** design §14–§16, decisions D-07 through D-10 - **설계 출처:** 설계 §14–§16, 결정 D-07부터 D-10
## Context ## 배경
MongoDB reports two transaction failures that look similar and must be handled in opposite ways. MongoDB는 비슷해 보이지만 정반대로 다뤄야 하는 트랜잭션 실패 둘을 알린다.
`TransientTransactionError` means the transaction definitively did not commit. The correct response is `TransientTransactionError`는 트랜잭션이 분명히 커밋되지 않았다는 뜻이다. 맞는 대응은 전체를 다시 돌리는 것이다.
to run the whole thing again.
`UnknownTransactionCommitResult` means the commit **may already have applied** — typically because the `UnknownTransactionCommitResult`는 커밋이 **이미 적용됐을 수 있다**는 뜻이다 — 보통 커밋이 진행 중일 때 primary가 바뀌었기
primary changed while the commit was in flight. The correct response is to retry *the commit*, which 때문이다. 맞는 대응은 *커밋*을 재시도하는 것이고, 이미 성공했다면 그것은 아무 일도 하지 않는다.
is a no-op if it already succeeded.
The common implementation wraps everything in one retry loop. That loop replays the body after an 흔한 구현은 모든 것을 재시도 반복문 하나로 감싼다. 그 반복문은 모르는 커밋 뒤에 본문을 다시 돌리고, 커밋이 적용됐었다면 본문이
unknown commit, and if the commit did apply, the body applies twice. In a payment or notification path 두 번 적용된다. 결제나 알림 경로에서 그것은 오류 handler가 만든 중복 청구나 중복 메시지다.
that is a duplicate charge or a duplicate message, produced by the error handler.
The related trap is session reuse: retrying on the same session after an abort carries the aborted 관련된 함정은 세션 다시 쓰기다: abort 뒤에 같은 세션으로 재시도하면 abort된 트랜잭션의 상태가 재시도로 넘어간다.
transaction's state into the retry.
## Decision ## 결정
`MongoTransactionRetryCoordinator` implements two loops with different scopes. `MongoTransactionRetryCoordinator`가 범위가 다른 반복문 둘을 구현한다.
``` ```
for each body attempt within the budget: for each body attempt within the budget:
@@ -44,34 +40,30 @@ for each body attempt within the budget:
UnknownTransactionCommitResult -> retry the COMMIT ONLY, same session UnknownTransactionCommitResult -> retry the COMMIT ONLY, same session
``` ```
Rules that follow, all of them load-bearing: 따라 나오는 규칙. 모두 꼭 필요하다:
1. **A new session per body attempt.** No aborted state leaks into a retry. 1. **본문 시도마다 새 세션.** abort된 상태가 재시도로 새지 않는다.
2. **The body is never replayed after a commit ambiguity.** `MongoRetryScope.COMMIT_ONLY` is a 2. **커밋이 모호해진 뒤에는 본문을 절대 다시 돌리지 않는다.** `MongoRetryScope.COMMIT_ONLY`가 `BODY`와 다른 값인 것은 바로
distinct value from `BODY` precisely so this cannot be collapsed by accident. 이것이 실수로 뭉개지지 않게 하려는 것이다.
3. **One budget bounds both loops.** `MongoRetryBudget` limits attempts *and* elapsed time, with 3. **예산 하나가 두 반복문을 묶는다.** `MongoRetryBudget`이 시도 수 *그리고* 흐른 시간을 jitter 있는 backoff와 함께 제한한다.
jittered backoff, so a struggling primary is not retried into the ground by every instance at once. 그래서 힘든 primary를 모든 인스턴스가 한꺼번에 재시도로 짓밟지 않는다.
4. **An exhausted commit retry surfaces `TRANSACTION_COMMIT_UNKNOWN`,** never a generic failure. An 4. **바닥난 커밋 재시도는 일반 실패가 아니라 `TRANSACTION_COMMIT_UNKNOWN`으로 드러난다.** 실패로 알린 모호한 결과는 호출자에게
ambiguous outcome reported as a failure invites the caller to retry — the one thing that must not 재시도를 부른다 — 일어나면 안 되는 바로 그 일이다.
happen. See [docs/mongodb/runbooks/unknown-commit.md](../mongodb/runbooks/unknown-commit.md). [docs/mongodb/runbooks/unknown-commit.md](../mongodb/runbooks/unknown-commit.md)를 본다.
5. **Transaction bodies write a deterministic marker** so `MongoCommitReconciler` can establish what 5. **트랜잭션 본문은 결정적인 표지를 쓴다.** 그래서 `MongoCommitReconciler`가 실제로 무엇이 일어났는지 세울 수 있다. 맞춰 볼 수
actually happened. A transaction that cannot be reconciled has no recovery path. 없는 트랜잭션에는 회복 길이 없다.
6. **Classification reads labels before codes.** Server error labels are the authoritative statement 6. **분류는 코드보다 label을 먼저 읽는다.** 서버 오류 label이 재시도 가능성에 대한 정본 진술이고, 오류 코드는 버전마다 다르다.
about retryability; error codes vary by version.
Surrounding decisions that reduce how often this path is reached at all: single-document atomic 이 경로에 닿는 횟수 자체를 줄이는 주변 결정: 트랜잭션보다 단일 문서 원자 연산을 고른다(D-09), 부분 변경은 `save()`가 아니라
operations are preferred over transactions (D-09), partial changes use update operators rather than update 연산자를 쓴다(D-07), 문서 전체 바꾸기에는 낙관적 revision이 필요하다(D-08).
`save()` (D-07), and whole-document replacement requires an optimistic revision (D-08).
## Consequences ## 결과
**Positive.** A commit ambiguity cannot become a duplicate effect. The ambiguity reaches the caller as **좋은 점.** 커밋 모호함이 중복 효과가 될 수 없다. 모호함이 모호함으로 호출자에게 닿는다. 재시도 예산이 시도 수와 시간 둘 다에서
an ambiguity. The retry budget is bounded in both attempts and time. 한계를 가진다.
**Negative.** Callers must handle a third outcome beyond success and failure. Transaction bodies must **나쁜 점.** 호출자는 성공과 실패 밖의 세 번째 결과를 다뤄야 한다. 트랜잭션 본문은 그렇지 않으면 필요 없을 표지를 써야 한다. 두
write a marker they would not otherwise need. Both costs are small compared with reconciling 비용 모두 중복된 금전 효과를 나중에 맞춰 보는 것에 비하면 작다.
duplicated financial effects after the fact.
**Rejected alternative — "one retry loop, at-least-once everywhere."** It requires every transaction **버린 대안 — 「재시도 반복문 하나, 어디서나 at-least-once」.** 모든 트랜잭션 본문이 완전히 멱등이어야 한다. 표지 하나를 쓰는
body to be fully idempotent, which is a much stronger and much less checkable property than writing 것보다 훨씬 강하고 훨씬 검사하기 어려운 성질이고, 누가 멱등이 아닌 단계를 처음 더하는 순간 소리 없이 깨진다.
one marker, and it is silently violated the first time someone adds a non-idempotent step.
@@ -7,65 +7,55 @@
- 현재 정본: `docs/mongodb/schema-index-migration-guide.md` - 현재 정본: `docs/mongodb/schema-index-migration-guide.md`
<!-- 머리 블록 끝 --> <!-- 머리 블록 끝 -->
# ADR-MONGO-004 — Index and schema changes belong to the admin plane # ADR-MONGO-004 — index와 schema 변경은 admin plane의 것이다
- **Status:** Accepted - **상태:** 채택
- **Date:** 2026-08-13 - **날짜:** 2026-08-13
- **Design source:** design §21–§25, decisions D-11, D-13 - **설계 출처:** 설계 §21–§25, 결정 D-11, D-13
## Context ## 배경
Spring Data can create indexes automatically from annotations. On a laptop this is convenient. On a Spring Data는 애너테이션에서 index를 자동으로 만들 수 있다. 노트북에서는 편하다. 문서 1억 개가 든 collection에서 index 만들기는
collection with a hundred million documents, an index build is a capacity event: it consumes CPU, IO 용량 사건이다: primary의 CPU, IO, 메모리를 몇 분에서 몇 시간 동안 쓰고, pod 하나가 재시작했다는 이유로 시작된다.
and memory on the primary for minutes to hours, and it starts because a pod restarted.
Worse, it starts N times when N pods restart, and there is no approval step, no ordering relative to 더 나쁘게, pod N개가 재시작하면 N번 시작하고, 승인 단계도, 그 index가 필요한 코드와의 순서도, 나중에 무엇을 만들었는지의 기록도
the code that needs the index, and no record afterwards of what was created. 없다.
Schema validators have the same shape with a sharper edge: tightening a validator on a collection with schema validator도 같은 모양인데 날이 더 서 있다: 데이터가 있는 collection에서 validator를 조이면, 쓸 때는 적법했던 문서에 대한
existing data rejects writes to documents that were legal when they were written. 쓰기를 거절한다.
TTL has a third shape. It looks like a scheduler and is not one: the TTL monitor runs about once a TTL은 세 번째 모양이다. scheduler처럼 보이지만 아니다: TTL monitor는 대략 1분에 한 번 돌고 batch로 지우므로, 만료된 문서가 몇
minute and deletes in batches, so an expired document routinely remains readable for minutes or hours. 분에서 몇 시간 동안 읽히는 것이 예사다.
## Decision ## 결정
**Indexes and validators are declared in a manifest and applied by the admin plane (D4).** Automatic **index와 validator는 manifest에 선언하고 admin plane(D4)이 적용한다.** 운영에서 자동 index 만들기는 끈다.
index creation in production is disabled.
1. `MongoManifestRegistry` holds the declared indexes (`MongoIndexManifest`) and validator 1. `MongoManifestRegistry`가 collection마다 선언한 index(`MongoIndexManifest`)와 validator(`MongoSchemaManifest`)를 가진다.
(`MongoSchemaManifest`) per collection. The manifest is the source of truth, reviewed in a pull manifest가 정본이고 pull request에서 리뷰한다.
request. 2. `MongoIndexDiffEngine`이 manifest를 관찰한 상태와 비교해 빠진 index, 남는 index, *바뀐* index를 알린다. 바뀐 것은 다시 내지
2. `MongoIndexDiffEngine` compares manifest against observed state and reports missing, extra and 않고 알린다: MongoDB는 정의가 움직인 index를 소리 없이 다시 만들지 않는다.
*changed* indexes. Changed ones are reported rather than re-issued: MongoDB will not silently 3. `MongoIndexApplyPolicy`가 환경이 할 수 있는 것을 정한다 — `APPLY`(로컬), `APPLY_WITH_DIFF`(staging),
rebuild an index whose definition moved. `DIFF_WITH_APPROVED_APPLY`(운영), `REPORT_ONLY`(감사).
3. `MongoIndexApplyPolicy` sets what an environment may do — `APPLY` (local), `APPLY_WITH_DIFF` 4. **모든 drop은 소유권이 막는다.** `MongoMetadataOwnership`이 `APPLICATION_MANAGED`를 `SEARCH_MANAGED`, `ENCRYPTION_MANAGED`,
(staging), `DIFF_WITH_APPROVED_APPLY` (production), `REPORT_ONLY` (audit). `EXTERNAL`과 구별한다. 어긋났을 때 지울 수 있는 것은 애플리케이션이 관리하는 객체뿐이다. 소유권 없는 diff 엔진은 결국
4. **Ownership gates every drop.** `MongoMetadataOwnership` distinguishes `APPLICATION_MANAGED` from `enxcol_.customers.esc`를 지우자고 제안하고, 「drift 도구가 치웠다」는 아주 나쁜 사고 요약이다.
`SEARCH_MANAGED`, `ENCRYPTION_MANAGED` and `EXTERNAL`. Only application-managed objects are 5. **은퇴는 단계를 밟는다.** `MongoIndexRetirementState`가 index를 선언됨 → 숨김 → 안 쓰는 것 확인 → 지울 수 있음으로 옮기고,
droppable on drift. A diff engine without ownership eventually proposes dropping 전이마다 배포 한 번이다. 숨기기는 바로 되돌릴 수 있다. 지우기는 다시 만들기다.
`enxcol_.customers.esc`, and "the drift tool cleaned it up" is a very bad incident summary. 6. **Stable validation action은 `error`와 `warn`뿐이다.** `errorAndLog`는 7.0이나 8.0에서 Stable 계약에 속하지 않아 거절한다.
5. **Retirement is staged.** `MongoIndexRetirementState` moves an index declared → hidden → 조이기는 `warn`+`MODERATE` → 경고 0 확인 → `error`+`STRICT`로, 배포 두 번에 걸쳐 간다.
observed-unused → droppable, one deployment per transition. Hiding is instantly reversible; 7. **TTL은 물리적 치우기일 뿐이다**(D-13). `MongoExpirationAccessPolicy`가 규칙을 말한다: 문서가 있다고 인가가 아니고, 없다고
dropping is a rebuild. 기한이 아니다. 접근 통제는 만료 필드를 검사하고, 일정은 scheduler를 쓴다.
6. **Stable validation actions are `error` and `warn` only.** `errorAndLog` is not part of the Stable 8. **migration은 checksum을 두고, 잠그고, 전제 조건을 검사하고, 이어서 할 수 있다.** `MongoMigrationRunner`는 적용한 id의
contract on 7.0 or 8.0 and is refused. Tightening goes `warn`+`MODERATE` → confirm zero warnings → checksum이 바뀌면 단단히 실패한다 — 두 환경이 id 하나 아래 다른 코드를 돌리는 것은 실패한 배포보다 나쁘다.
`error`+`STRICT`, in two deployments.
7. **TTL is physical cleanup only** (D-13). `MongoExpirationAccessPolicy` states the rule: a
document's presence is not authorization and its absence is not a deadline. Access control checks
the expiry field; scheduling uses a scheduler.
8. **Migrations are checksummed, locked, precondition-checked and resumable.**
`MongoMigrationRunner` fails hard when an applied id's checksum changed — two environments running
different code under one id is worse than a failed deploy.
## Consequences ## 결과
**Positive.** Index builds are scheduled by people who know the capacity. Rollback is possible at **좋은 점.** index 만들기 일정은 용량을 아는 사람이 잡는다. 모든 단계에서 되돌릴 수 있다. drift는 위험하지 않게 보인다. 아무것도
every step. Drift is visible without being dangerous. Nothing drops what it does not own. 자기가 가지지 않은 것을 지우지 않는다.
**Negative.** Adding an index is a manifest change plus an apply, not an annotation. Local development **나쁜 점.** index 더하기는 애너테이션이 아니라 manifest 변경 + 적용이다. 로컬 개발은 `APPLY`를 쓰므로 마찰은 그것이 정당한
uses `APPLY` so the friction is confined to environments where it is warranted. 환경에만 머문다.
**Rejected alternative — "auto-create with a feature flag."** The flag is either on in production, **버린 대안 — 「feature flag와 함께 자동으로 만들기」.** flag가 운영에서 켜져 있으면 그것이 문제이고, 꺼져 있으면 manifest가
which is the problem, or off, in which case the manifest is the real mechanism and the annotation is a 실제 장치이고 애너테이션은 두 번째의 갈라진 정본이다.
second, divergent source of truth.
@@ -7,90 +7,78 @@
- 현재 정본: `docs/mongodb/support-matrix.md` - 현재 정본: `docs/mongodb/support-matrix.md`
<!-- 머리 블록 끝 --> <!-- 머리 블록 끝 -->
# ADR-MONGO-ADV-001 — Advanced capability promotion # ADR-MONGO-ADV-001 — Advanced capability 승격
- **Status:** Accepted - **상태:** 채택
- **Date:** 2026-08-13 - **날짜:** 2026-08-13
- **Design source:** design §2 (D-15), §3.2–§3.3; Advanced expansion plan Task 15 - **설계 출처:** 설계 §2 (D-15), §3.2–§3.3. Advanced 확장 계획 Task 15
- **Amended 2026-09-25:** the `ca-skeleton.persistence-mongo.advanced.*.enabled` binding - **2026-09-25 보완:** `ca-skeleton.persistence-mongo.advanced.*.enabled` 바인딩(`MongoAdvancedConfiguration`/
(`MongoAdvancedConfiguration`/`MongoAdvancedSettings`) was imported by nothing, so no deployment `MongoAdvancedSettings`)은 아무것도 import하지 않아서 어떤 배포 속성도 flag에 닿지 않았다. `propertyFor`와 함께 지웠다. flag는
property ever reached the flags; it was removed together with `propertyFor`. The flags are now 이제 entry point를 만드는 어댑터가 코드로 만든다. `MongoAdvancedPromotionGate`, `MongoAdvancedPromotionEvidence`,
built in code by the adapter that constructs an entry point. `MongoAdvancedPromotionGate`, `MongoVectorSearchBenchmarkGate`, 그리고 search, vector, time series, GridFS 패키지(구현 없는 인터페이스)를 지웠다. 아래 증거
`MongoAdvancedPromotionEvidence`, `MongoVectorSearchBenchmarkGate` and the search, vector, time category는 리뷰 의무로 남는다. 그것을 검사하는 클래스는 없다.
series and GridFS packages (interfaces with no implementation) were removed. The evidence
categories below remain a review obligation; no class checks them.
## Context ## 배경
Sharding, time series, CSFLE, Queryable Encryption, search, vector search and multi-tenancy each work sharding, time series, CSFLE, Queryable Encryption, search, vector search, multi-tenancy는 하나같이 오후 한나절이면 demo에서
in a demo within an afternoon. What they do not do is behave the same way in production, and the 동작한다. 하지 않는 것은 운영에서 같은 방식으로 동작하는 것이고, 그 차이는 기능 시험으로 찾지 못한다:
differences are not discovered by functional tests:
- Sharding changes which queries are efficient. A query that misses the shard key becomes - sharding은 어떤 query가 효율적인지 바꾼다. shard key를 놓친 query는 scatter-gather가 되는데, shard 하나짜리 cluster에서는
scatter-gather, which passes every test on a one-shard cluster. 모든 시험을 통과한다.
- Encryption's failure modes are KMS failure modes — wrong key, revoked permission, mid-rotation — - 암호화의 실패 방식은 KMS의 실패 방식이다 — 틀린 키, 거둬들인 권한, 교체 중 — 로컬 키 provider에 대고는 하나도 일어나지 않는다.
none of which occur against a local key provider. - search와 vector search는 기능상 맞으면서 쓸모없을 수 있다: index는 결과를 돌려주는데 결과가 관련이 없다. recall은 통과·실패
- Search and vector search can be functionally correct and useless: the index returns results, and 단언에 보이지 않는다.
the results are not relevant. Recall is not visible in a pass/fail assertion. - 테넌트마다 데이터베이스는 테넌트 수가 연결·파일 handle 예산이 받쳐 주는 수를 넘을 때까지 동작한다. 그것은 코드가 아니라 운영의
- Database-per-tenant works until the tenant count crosses what the connection and file-handle 성질이다.
budget supports, which is an operational property, not a code property.
The failure mode this ADR prevents is a capability marked "done" on the strength of a green test that 이 ADR이 막는 실패 방식은 그것이 돌 환경을 한 번도 건드리지 않은 초록 시험을 근거로 capability를 「끝남」으로 표시하는 것이다.
never touched the environment where it will run.
## Decision ## 결정
Every Advanced and Experimental capability is an **opt-in module behind its own flag**, and promotion 모든 Advanced·Experimental capability는 **자기 flag 뒤의 골라 쓰는 모듈**이고, 승격에는 자신감이 아니라 증거가 필요하다.
requires evidence, not confidence.
### Enablement ### 켜기
`MongoAdvancedCapabilityFlags` gates construction of every Advanced entry point. A disabled capability `MongoAdvancedCapabilityFlags`가 모든 Advanced entry point의 생성을 막는다. 꺼진 capability는 런타임 경고를 내지 않는다 — 타입이
does not produce a runtime warning — the type refuses to be constructed, naming the property that 그것을 켜는 속성 이름을 대며 만들어지기를 거절한다(`MongoAdvancedCapabilityFlags.propertyFor(capability)`). classpath에 있다고
enables it (`MongoAdvancedCapabilityFlags.propertyFor(capability)`). Being on the classpath is not 켜진 것이 아니고, `stableNeverDependsOnAdvanced`(ArchUnit)가 Stable surface에서 그것을 떼어 둔다.
being enabled, and `stableNeverDependsOnAdvanced` (ArchUnit) keeps the Stable surface free of them.
### Promotion evidence ### 승격 증거
`MongoAdvancedPromotionGate.verify(evidence)` requires every category: `MongoAdvancedPromotionGate.verify(evidence)`는 모든 category를 요구한다:
| Category | Means | | category | 뜻 |
|---|---| |---|---|
| `stable-platform` | The Stable release gate passed on the same revision. | | `stable-platform` | 같은 revision에서 Stable 릴리스 gate가 통과했다. |
| `actual-topology` | The capability ran on the real topology — a real sharded cluster, the real KMS, the actual target deployment. Atlas Local is a pull-request convenience and explicitly not release evidence (`MongoAtlasCapabilityContractSuite.Environment.ATLAS_LOCAL`). | | `actual-topology` | capability가 실제 topology에서 돌았다 — 실제 sharded cluster, 실제 KMS, 실제 대상 배포. Atlas Local은 pull request용 편의이고 릴리스 증거가 아님을 명시한다(`MongoAtlasCapabilityContractSuite.Environment.ATLAS_LOCAL`). |
| `security` | Privileges reviewed; the capability's admin role is separate from the application role. | | `security` | 권한을 리뷰했다. capability의 admin role은 애플리케이션 role과 따로다. |
| `migration` | A documented path in and, where the capability is irreversible, an explicit statement that there is no path back. | | `migration` | 들어가는 길을 적었고, capability가 되돌릴 수 없으면 돌아오는 길이 없다고 명시했다. |
| `failure` | Negative cases fail closed: wrong key, missing permission, rotation, non-ready index, unrouted query. | | `failure` | 부정 경우가 실패하면 닫힌다: 틀린 키, 빠진 권한, 교체, 준비되지 않은 index, 라우팅되지 않은 query. |
| `runbook` | A runbook exists for the capability's characteristic incident. | | `runbook` | capability의 대표 사고를 위한 runbook이 있다. |
### Additional per-capability requirements ### capability별 추가 요구
- **Search / vector search:** relevance and performance evidence, not functional success alone. - **search / vector search:** 기능 성공만이 아니라 관련성과 성능 증거. `MongoVectorSearchBenchmarkGate`는 지연 시간·index 크기와
`MongoVectorSearchBenchmarkGate` requires recall alongside latency and index size; a gate that 함께 recall을 요구한다. 지연 시간만 재는 gate는 빠른 틀린 답을 인증한다.
measures only latency certifies a fast wrong answer. - **테넌트마다 데이터베이스와 reshard 조율은 운영 규모 증거가 생길 때까지 Experimental로 남는다.** 둘 다 작게는 맞고 크게는
- **Database-per-tenant and reshard orchestration remain Experimental** until operational scale 한계가 없다.
evidence exists. Both are correct in the small and unbounded in the large. - **reshard에는 명시한 `ReshardApproval`이 필요하다** — 이름 있는 승인자와 밝힌 시간 창. reshard는 collection을 다시 쓴다.
- **Reshard requires an explicit `ReshardApproval`** — a named approver and a stated window. It
rewrites the collection.
### Promotion does not change the dependency boundary ### 승격은 의존 경계를 바꾸지 않는다
A capability promoted to Stable **remains an opt-in module** unless a later starter ADR changes the Stable로 승격한 capability도 나중의 starter ADR이 의존 경계를 바꾸지 않는 한 **골라 쓰는 모듈로 남는다**. 승격은 증거에 대한
dependency boundary. Promotion is a statement about evidence, not an invitation to add a transitive 진술이지, 모든 서비스에 전이 의존을 더하라는 초대가 아니다.
dependency to every service.
## Consequences ## 결과
**Positive.** No capability reaches production on the strength of a container-only test. The evidence **좋은 점.** container 전용 시험을 근거로 운영에 닿는 capability는 없다. 증거 목록이 모든 capability에 같으므로, 승격은 흥정이
list is the same for every capability, so promotion is reviewable rather than negotiated. 아니라 리뷰할 수 있는 것이 된다.
**Negative.** Promotion requires access to real infrastructure — a sharded cluster, a real KMS, the **나쁜 점.** 승격에는 실제 기반 시설 — sharded cluster, 실제 KMS, 대상 배포 — 에 대한 접근이 필요하다. 그것이 보장의 비용이다:
target deployment. That is the cost of the guarantee: the alternative is finding out in production, 대안은 운영에서 알게 되는 것이고, 거기서는 암호화와 sharding 둘 다 되돌리기 비싸다.
where encryption and sharding are both expensive to reverse.
## Verification ## 검증
`scripts/verify-mongodb-advanced.sh` enforced this ADR until it was removed on 2026-08-15. The `scripts/verify-mongodb-advanced.sh`가 2026-08-15에 지워질 때까지 이 ADR을 강제했다. 그래서 이 ADR이 요구하는 승격 증거
promotion evidence categories this ADR requires are therefore no longer checked by any automated category는 이제 어떤 자동 gate도 검사하지 않는다. 다시 만들 때까지 리뷰 의무다. 그 script가 감싸던 Gradle lane은
gate; they are a review obligation until one is rebuilt. See `docs/mongodb/repository-adaptation.md` `docs/mongodb/repository-adaptation.md` §5를 본다.
§5 for the Gradle lanes the script wrapped.
@@ -7,73 +7,62 @@
- 현재 정본: `docs/web/streaming-contract.md` - 현재 정본: `docs/web/streaming-contract.md`
<!-- 머리 블록 끝 --> <!-- 머리 블록 끝 -->
# ADR-WEB-ADV-001: Streaming is live delivery, and the web module stores no history # ADR-WEB-ADV-001: streaming은 실시간 전달이고, web 모듈은 이력을 저장하지 않는다
- Status: Accepted - 상태: 채택
- Date: 2026-08-25 - 날짜: 2026-08-25
- Scope: `adapter:inbound:web` — `advanced.stream.**` - 범위: `adapter:inbound:web` — `advanced.stream.**`
## Context ## 배경
Advanced Tasks 6–13 add SSE, NDJSON and JSON text sequences, with a `Last-Event-ID` resume path. Advanced Task 6–13은 `Last-Event-ID` resume 경로와 함께 SSE, NDJSON, JSON text sequence를 더한다.
One fact drives every decision here: **after the first byte, the HTTP status is 200 and cannot 여기의 모든 결정을 이끄는 사실은 하나다: **첫 바이트 뒤에 HTTP status는 200이고 바꿀 수 없다.** 의존 대상이 실패해서 끝난
change.** A stream that ends because a dependency failed and one that ends because it finished are stream과 다 마쳐서 끝난 stream은 전송 계층에서 똑같다 — 둘 다 200 뒤에 닫힌 연결이다. 도중에 잘린 stream도 그렇다.
identical at the transport layer — both are a closed connection after a 200. So is a stream that was
cut off mid-flight.
The second fact is that a resume path invites the web module to remember things. It must not: the 둘째 사실은 resume 경로가 web 모듈에게 무언가를 기억하라고 꾄다는 것이다. 그러면 안 된다: durable 이벤트 이력은 이미 메시징
messaging platform already owns durable event history, and a second copy would have its own 플랫폼이 가지고, 두 번째 사본은 자기 보존 기간, 자기 eviction, 순서에 대한 자기 의견을 가질 것이다.
retention, its own eviction and its own opinion about ordering.
## Decision ## 결정
**Three outcomes, expressed in the stream rather than in the status.** The wire record (for NDJSON, **결과는 셋이고, status가 아니라 stream 안에서 나타낸다.** wire record(NDJSON이면 `NdjsonRecord`)는 항목, 실패, 완료 중 하나다.
`NdjsonRecord`) is an item, a failure or a completion. A client that sees neither terminal record 끝 record를 하나도 보지 못한 client는 잘린 것이고, 그 셋째 경우는 완료로 세지 않고 `ABRUPT_CLOSE`로 기록한다 — 그렇지 않으면
has been cut off, and that third case is recorded as `ABRUPT_CLOSE` rather than counted as a 도중 실패 비율이 오르는 것이 거기 숨는다.
completion — which is where a rising rate of mid-stream failures would otherwise hide.
**Nothing writes an error body onto a committed response.** Before commit, a failure is an ordinary **커밋된 응답 위에 오류 body를 쓰는 것은 없다.** 커밋 전의 실패는 실제 status를 가진 보통 HTTP 오류(`Envelope`)이고, 커밋 뒤에는
HTTP error (the `Envelope`) with a real status; after, a terminal record. Attempting both produces a 끝 record다. 둘 다 하려 하면 반은 stream이고 반은 JSON인 body가 나오는데, 어떤 client도 그것을 파싱하지 못하고 모든 proxy가
body that is half stream and half JSON, which no client parses and every proxy caches as a success. 성공으로 cache한다. (이것을 인코딩하던 mapper `WebStreamTerminationMapper`는 그것이 돌려주던 problem document 어휘와 함께
(The mapper that encoded this, `WebStreamTerminationMapper`, was removed on 2026-09-25 with the 2026-09-25에 지웠다. 규칙은 남는다.)
problem-document vocabulary it returned; the rule stands.)
**Positions are monotonic, and it is enforced.** `WebStreamEvidence.recordDelivered` refuses a **위치는 단조 증가하고, 그것을 강제한다.** `WebStreamEvidence.recordDelivered`는 되풀이되거나 뒤로 가는 위치를 거절한다. 위치로
repeated or regressing position. A client deduplicating on position would silently drop the second 중복을 거르는 client는 두 번째 항목을 소리 없이 버리게 된다.
item.
**A slow consumer is disconnected, not buffered.** `WebStreamPolicy.maxBufferedItems` is a hard **느린 소비자는 buffer에 담지 않고 연결을 끊는다.** `WebStreamPolicy.maxBufferedItems`는 단단한 한계다. backpressure는 reactive
bound. Backpressure protects the reactive pipeline; it does not protect the server's heap from a pipeline을 지키지만, 한 시간 동안 천천히 읽는 소비자로부터 서버 heap을 지키지는 않는다.
consumer that reads slowly for an hour.
**Every stream is in a registry, and shutdown drains it.** A node with a hundred open streams and no **모든 stream은 registry에 있고, 종료가 그것을 비운다.** 열린 stream 백 개 말고 다른 traffic이 없는 노드는 요청 비율로 보면 놀고
other traffic looks idle by request rate. `WebStreamDrainCoordinator` stops accepting first, asks 있는 것처럼 보인다. `WebStreamDrainCoordinator`는 먼저 받기를 멈추고, client에게 다시 연결하라고 요청하고, 그다음에야 나머지를
clients to reconnect, and only then forces the remainder — because a client whose socket is cut 강제로 끊는다 — socket이 끊긴 client는 바로 다시 시도하고, 모든 socket을 한꺼번에 끊으면 모든 client가 한꺼번에 다시 시도하기
retries immediately, and if every socket is cut at once, every client retries at once. 때문이다.
**The web module stores no durable history.** `WebStreamReplaySource` is an interface this module **web 모듈은 durable 이력을 저장하지 않는다.** `WebStreamReplaySource`는 이 모듈이 어디에서도 구현하지 않는 인터페이스다. 만료된
implements nowhere. An expired cursor raises `ReplayCursorExpiredException` rather than resuming from cursor는 보존한 가장 오래된 위치에서 이어 가지 않고 `ReplayCursorExpiredException`을 올린다. 그렇게 하면 client가 볼 수 없는
the oldest retained position, because that delivers a stream with a hole the client cannot see. 구멍이 있는 stream을 전달하기 때문이다.
**The replay-to-live seam is watched.** `GapAndDuplicateGuard` detects both directions. Neither is **재생에서 실시간으로 넘어가는 이음매를 지켜본다.** `GapAndDuplicateGuard`가 두 방향을 모두 찾는다. 어느 쪽도 한 절반만 보면
visible in either half on its own. 보이지 않는다.
## Consequences ## 결과
- Clients must handle three outcomes. A client that treats a closed connection as completion will be - client는 결과 셋을 다뤄야 한다. 닫힌 연결을 완료로 다루는 client는 틀리고, 서버가 무엇을 바꿔도 그것을 대신 고칠 수 없다.
wrong, and no server change can fix that for it. - 만료된 `Last-Event-ID`는 client에게 전체 다시 읽기를 치르게 한다. 그것이 정직한 답이다.
- An expired `Last-Event-ID` costs the client a full re-read. That is the honest answer. - 잘림이 중요한 곳에서는 NDJSON보다 JSON-seq를 고른다: 구분자가 앞에 오므로 parser가 다음 record에서 다시 맞춘다. NDJSON의
- JSON-seq is preferred over NDJSON where truncation matters: its separator comes first, so a parser 구분자는 잘려 나가는 바로 그것이다.
resynchronises at the next record. NDJSON's delimiter is the thing that gets truncated away.
## Alternatives considered ## 따져 본 대안
- **Emit a problem document when a stream fails after commit.** Rejected: the body becomes - **커밋 뒤에 stream이 실패하면 problem document를 낸다.** 버렸다: body가 파싱할 수 없게 되고 200이 cache된다.
unparseable and the 200 is cached. - **cursor가 만료되면 보존한 가장 오래된 위치에서 이어 간다.** 버렸다: 위치는 재생이 시작된 곳부터 이어지므로, 데이터 안의 어떤
- **Resume from the oldest retained position when the cursor expires.** Rejected: positions are 것도 이벤트가 빠졌다고 말하지 않는다.
contiguous from where the replay started, so nothing in the data says events are missing. - **재생 이력을 web 모듈에 저장한다.** 버렸다: 보이지 않게 어긋나는 두 번째 정본이다.
- **Store replay history in the web module.** Rejected: a second source of truth that drifts - **느린 소비자를 위한 한계 없는 buffer.** 버렸다: client의 느림을 서버 heap으로 옮긴다.
invisibly.
- **Unbounded buffering for slow consumers.** Rejected: it moves the client's slowness into the
server's heap.
@@ -7,73 +7,60 @@
- 현재 정본: `docs/web/virtual-thread-profile.md` - 현재 정본: `docs/web/virtual-thread-profile.md`
<!-- 머리 블록 끝 --> <!-- 머리 블록 끝 -->
# ADR-WEB-ADV-002: Virtual threads change scheduling, not the concurrency budget # ADR-WEB-ADV-002: virtual thread는 스케줄링을 바꾸지 동시성 예산을 바꾸지 않는다
- Status: Accepted - 상태: 채택
- Date: 2026-08-25 - 날짜: 2026-08-25
- Scope: `adapter:inbound:web` — `advanced.virtualthread`, `advanced.blockingbridge` - 범위: `adapter:inbound:web` — `advanced.virtualthread`, `advanced.blockingbridge`
## Context ## 배경
Advanced Task 2 offers a virtual-thread executor for MVC; Task 3 offered a bounded blocking bridge Advanced Task 2는 MVC용 virtual thread executor를 준다. Task 3은 WebFlux용 한계 있는 blocking bridge를 줬다. (그 WebFlux 어댑터는
for WebFlux. (The WebFlux adapter for it was removed on 2026-09-25 — the template is servlet only; 2026-09-25에 지웠다 — 템플릿은 servlet만이다. `advanced.blockingbridge`는 라이브러리 코드로 남는다.)
`advanced.blockingbridge` remains as library code.)
A platform-thread MVC deployment has an implicit concurrency limit — the thread pool — and that platform thread MVC 배포에는 숨은 동시성 한계 — thread pool — 가 있고, 보통 그 한계가 데이터베이스 pool, outbound HTTP
limit is usually what has been protecting the database pool, the outbound HTTP bulkhead and every bulkhead, 모든 하류 서비스를 전체 도착 비율로부터 지켜 왔다. 아무도 그것을 admission 정책으로 적지 않았다. pool 크기의
downstream service from the full arrival rate. Nobody wrote it down as an admission policy; it was a 부작용이었다.
side effect of the pool size.
Switching to virtual threads deletes that limit without deleting anything that depended on it. virtual thread로 바꾸면 그 한계가 지워지는데, 그것에 기대던 것은 하나도 지워지지 않는다.
## Decision ## 결정
**An explicit admission limit is required when virtual threads are enabled.** **virtual thread를 켜면 명시적 admission 한계가 필요하다.** `VirtualThreadProfile`은 그것 없이는 만들어지기를 거절한다. 없으면
`VirtualThreadProfile` refuses construction without one. Without it the deployment accepts every 배포는 모든 도착을 받고, 그것을 모두 하류 예산 위에 줄 세우며, 거절됐으면 성공했을 일을 timeout으로 끝낸다. 예전에 정문에서
arrival, queues all of them on the downstream budgets, and times out work that would have succeeded 덜어 내던 부하를, 받아들이는 비용을 치른 뒤 뒷문에서 덜어 낸다.
had it been refused. The load that used to be shed at the front door is shed at the back, after the
cost of accepting it.
**The limit bounds concurrent use cases, not threads.** `VirtualThreadAdmissionGuard` is a fair **한계는 스레드가 아니라 동시 유스케이스를 묶는다.** `VirtualThreadAdmissionGuard`는 pool이 아니라 공정한 semaphore다. 스레드를
semaphore, not a pool. Bounding threads would put the waiting back and throw away what virtual 묶으면 기다림을 되돌려 놓고 virtual thread가 산 것을 버린다. virtual thread 만 개가 있어도 허가를 쥔 것은 백 개일 수 있다.
threads bought. Ten thousand virtual threads may exist while a hundred hold permits.
**The downstream budgets are carried in the profile and stated as unchanged.** The whole point is **하류 예산은 profile에 싣고 바뀌지 않았다고 밝힌다.** 요점은 그것이 늘지 않았다는 것이다. `admissionFitsDownstreamBudgets()`는
that they did not grow. `admissionFitsDownstreamBudgets()` reports when the admission limit exceeds admission 한계가 그것을 넘으면 거절하지 않고 알린다 — 일이 모두 데이터베이스에 묶인 것이 아니면 배포가 pool보다 많이 받는
them, without refusing — a deployment can legitimately admit more than its pool when the work is not 것이 정당할 수 있고, 그것은 사고가 아니라 선택이어야 한다.
all database-bound, and that should be a choice rather than an accident.
**Blocking offloads are registered, bounded and timed out.** `boundedElastic()` is available from **blocking offload는 등록하고, 한계를 두고, timeout을 둔다.** `boundedElastic()`은 어디서나 쓸 수 있고 실제로는 한계가 없어서,
anywhere and unbounded in practice, so a controller that calls it has silently opted the whole 그것을 부르는 controller는 애플리케이션 전체를 소리 없이 한계 없는 pool에 들여놓는다. `BlockingBridgeProfile`이 offload해도 되는
application into an unbounded pool. `BlockingBridgeProfile` names the operations permitted to operation을 이름으로 대고, `BlockingBridgeBudget`이 동시성을 묶으며 제때 자리를 얻지 못한 호출자를 거절한다. 그렇지 않으면 느린
offload; `BlockingBridgeBudget` bounds the concurrency and refuses a caller that cannot get a slot 의존 대상의 호출자가 heap이 찰 때까지 쌓이고 빠른 의존 대상이 그 뒤에서 굶는다.
in time, because otherwise a slow dependency's callers accumulate until the heap does and the fast
dependencies starve behind them.
> 2026-09-25: `advanced.blockingbridge` was removed. Its WebFlux adapter went with the WebFlux twin > 2026-09-25: `advanced.blockingbridge`를 지웠다. 그 WebFlux 어댑터는 WebFlux 쌍둥이와 함께 갔고(D4), 더는 없는 bridge의 예산은
> (D4), and a budget for a bridge that no longer exists bounded nothing. > 아무것도 묶지 않았다.
**Pinning is observed, not assumed away.** `VirtualThreadProfile.requiredObservations()` lists what **pinning은 없다고 치지 않고 관찰한다.** `VirtualThreadProfile.requiredObservations()`가 지켜봐야 할 것 — 무엇보다
has to be watched — `jdk.VirtualThreadPinned` above all. A synchronized block held across a blocking `jdk.VirtualThreadPinned` — 을 적는다. blocking 호출을 가로질러 쥔 synchronized 블록은 carrier thread를 고정하고, carrier pool은
call pins the carrier thread, the carrier pool is bounded by CPU count, and enough pinned carriers is CPU 수로 묶여 있으며, 고정된 carrier가 충분히 많으면 thread dump로도 잘 드러나지 않는 교착이 된다.
a deadlock a thread dump does not obviously show.
## Consequences ## 결과
- Enabling virtual threads is a two-part change: the executor and the admission limit. The profile - virtual thread 켜기는 두 부분짜리 변경이다: executor와 admission 한계. profile은 그것이 한 부분이 되게 두지 않는다.
will not let it be one. - 부하 아래에서 거절이 오르고, 그것이 맞다. 1밀리초 안에 거절된 요청이, 꽉 찬 pool 뒤에서 받아들여졌다가 30초 뒤 timeout된 같은
- Refusals rise under load, and that is correct. A request refused in a millisecond is better for 요청보다 client에게 낫다. 503이 오르는 것을 본 운영자는 그것을 한계가 동작하는 것으로 읽어야 한다.
the client than the same request accepted and timed out thirty seconds later behind a full pool. - `VirtualThreadAdmissionGuard.peakActive()`는 부하 시험이 한계가 적용됐음을 단언할 수 있게 하려고 있다. 처리량에서는 보이지
An operator seeing 503s climb should read them as the limit working. 않는다. 그래서 처리량만 재는 부하 시험은 guard를 빼도 통과한다.
- `VirtualThreadAdmissionGuard.peakActive()` exists so a load test can assert the limit was applied.
It is invisible from throughput, which is why a load test that only measures throughput would pass
with the guard removed.
## Alternatives considered ## 따져 본 대안
- **Enable virtual threads and raise the downstream budgets to match.** Rejected: the budgets are - **virtual thread를 켜고 하류 예산을 거기 맞춰 올린다.** 버렸다: 예산은 web 계층이 받을 수 있는 양이 아니라 의존 대상이 감당할
sized to what the dependencies can serve, not to what the web tier can accept. 수 있는 양에 맞춘 것이다.
- **Bound the virtual threads themselves with a fixed-size executor.** Rejected: that is a platform - **고정 크기 executor로 virtual thread 자체를 묶는다.** 버렸다: 단계만 더 많은 platform thread pool이다.
thread pool with extra steps. - **controller가 `boundedElastic()`을 직접 부르게 둔다.** 버렸다: 그런 호출 자리는 pool이 heap을 먹는 범인이 될 때까지 하나도
- **Let controllers call `boundedElastic()` directly.** Rejected: every such call site is invisible 보이지 않는다.
until the pool is the thing consuming the heap.
@@ -7,62 +7,51 @@
- 현재 정본: `docs/web/openapi-32-compatibility.md` - 현재 정본: `docs/web/openapi-32-compatibility.md`
<!-- 머리 블록 끝 --> <!-- 머리 블록 끝 -->
# ADR-WEB-ADV-003: OpenAPI 3.2 is generated in parallel and stays experimental # ADR-WEB-ADV-003: OpenAPI 3.2는 나란히 생성하고 실험용으로 남는다
- Status: Accepted - 상태: 채택
- Date: 2026-08-25 - 날짜: 2026-08-25
- Scope: `adapter:inbound:web` — `advanced.openapi` - 범위: `adapter:inbound:web` — `advanced.openapi`
## Context ## 배경
Advanced Task 17 adds an OpenAPI 3.2 generation lane beside the Stable 3.1.2 snapshot. Advanced Task 17은 Stable 3.1.2 snapshot 옆에 OpenAPI 3.2 생성 lane을 더한다.
Generating 3.2 is cheap. Adopting it is not, and the two get conflated because the generated 3.2 생성은 싸다. 채택은 싸지 않고, 생성된 문서가 멀쩡해 보여서 둘이 뒤섞인다. API 설명의 가치는 전부 그것을 쓰는 쪽에 있고,
document looks fine. The value of an API description is entirely in what consumes it, and a document client 생성기가 다 이해하지 못하는 버전의 문서는 컴파일되지만 틀린 client를 낳는다 — 문서가 아예 없는 것보다 나쁘다.
in a version a client generator does not fully understand produces a client that compiles and is
wrong — which is worse than no document at all.
## Decision ## 결정
**3.1.2 remains the release artifact.** `OpenApiVersionLane.STABLE_3_1.releaseArtifact()` is true and **3.1.2가 릴리스 artifact로 남는다.** `OpenApiVersionLane.STABLE_3_1.releaseArtifact()`는 true이고 `EXPERIMENTAL_3_2`의 것은
`EXPERIMENTAL_3_2`'s is false. This is a property of the type, not a configuration setting. false다. 이것은 설정이 아니라 타입의 성질이다.
**Generating 3.2 must not change the 3.1 snapshot.** Both are produced from the same model, so a **3.2를 생성해도 3.1 snapshot이 바뀌면 안 된다.** 둘은 같은 모델에서 만들어지므로, 3.2로 가는 길에 모델을 바꾸는 기여자는 실제로
contributor that mutates it on the way to 3.2 changes the artifact that is actually shipped — 출하하는 artifact를 바꾼다 — 소리 없이, 실험 lane이 돌 때만. `OpenApi32CompatibilityReport`가 전후의 snapshot hash를 비교하고,
silently, and only when the experimental lane runs. `OpenApi32CompatibilityReport` compares the 차이를 승격을 막는 것으로 만든다.
snapshot hash before and after and makes a difference a promotion blocker.
> 2026-09-25: `OpenApi32CompatibilityReport` and `OpenApiToolchainMatrix` were removed — promotion > 2026-09-25: `OpenApi32CompatibilityReport`와 `OpenApiToolchainMatrix`를 지웠다 — 운영 코드에 둔 승격 검사인데 자기 시험만
> checks kept in production code, called only by their own tests. `WebOpenApi32Generator` remains > 불렀다. `WebOpenApi32Generator`는 `adapter:inbound:web-advanced`에 라이브러리 코드로 남는다. 아래 결정은 바뀌지 않았다.
> as library code in `adapter:inbound:web-advanced`; the decision below is unchanged.
**Four kinds of tool are checked separately.** A parser reports structural errors; a linter applies **도구 네 종류를 따로 검사한다.** parser는 구조 오류를 알린다. linter는 문체 규칙을 적용하고 parser가 거절하는 문서도 받는다.
style rules and accepts documents a parser rejects; a generator produces client code, and this is 생성기는 client 코드를 만들고, 지원되지 않는 구문이 드러나는 곳이 여기다 — 오류가 아니라 시그니처가 틀린 메서드로. 그 생성 코드를
where an unsupported construct surfaces — not as an error but as a method with the wrong signature; 컴파일하는 것이 그것을 잡는 유일한 단계다. 「OpenAPI 3.2가 된다」는 누구도 할 수 있는 말이 아니다. 「이 문서를 이 버전의 이 네
a compile of that generated code is the only step that catches it. "OpenAPI 3.2 works" is not a 도구가 맞게 읽는다」는 할 수 있다.
statement anybody can make. "This document is read correctly by these four tools at these versions"
is.
**Promotion requires an accepted ADR regardless of how green the matrix is.** **표가 얼마나 초록이든 승격에는 채택된 ADR이 필요하다.** `promotionBlockers(false)`는 언제나 그 막음을 담는다. 기계로 검사하는
`promotionBlockers(false)` always contains that blocker. A machine-checkable matrix cannot decide 표는 쓰는 쪽 집단이 준비됐는지 정할 수 없다.
whether the consumer population is ready.
**Streaming description differences are reported separately.** They are the substantive difference **streaming 설명의 차이는 따로 알린다.** 이 애플리케이션에서 두 버전의 실질적 차이가 그것이고, 통과·실패 하나로 접으면 무엇이
between the two versions for this application, and folding them into a pass/fail hides what 바뀌었는지 가려진다.
changed.
## Consequences ## 결과
- The 3.2 document is published as an artifact of the experimental workflow, never of the release - 3.2 문서는 릴리스 workflow가 아니라 실험 workflow의 artifact로만 게시한다.
workflow. - 3.1만 이해하는 client 생성기는 영향을 받지 않는다. 그것이 요점이다.
- A client generator that only understands 3.1 is unaffected, which is the point. - 나중에 3.2를 채택하는 것은 이름 있는 쓰는 쪽 표를 뒤에 둔, 문서로 남긴 결정이다.
- Adopting 3.2 later is a documented decision with a named consumer matrix behind it.
## Alternatives considered ## 따져 본 대안
- **Switch to 3.2 and keep a 3.1 downgrade.** Rejected: the downgrade is lossy in exactly the - **3.2로 바꾸고 3.1로 낮춘 것을 둔다.** 버렸다: 낮추기는 바로 3.2를 원한 이유인 구문에서 손실이 있어서, 두 독자 모두에게 틀린
constructs 3.2 was wanted for, so it would ship a description that is wrong for both audiences. 설명을 출하하게 된다.
- **Generate only 3.2 and let consumers cope.** Rejected: the failure mode is a generated client - **3.2만 생성하고 쓰는 쪽이 알아서 하게 둔다.** 버렸다: 실패 방식은 컴파일되고 잘못 동작하는 생성 client다.
that compiles and misbehaves. - **표에서 client 컴파일 단계를 건너뛴다.** 버렸다: 다른 단계가 놓치는 실패를 잡는 유일한 단계다.
- **Skip the client-compile step in the matrix.** Rejected: it is the only one that catches the
failure the others miss.
@@ -8,62 +8,51 @@
- 대체됨: `docs/capability-status.md` - 대체됨: `docs/capability-status.md`
<!-- 머리 블록 끝 --> <!-- 머리 블록 끝 -->
# ADR-WS-001: The WebSocket platform ships as packages in one leaf, with machine-checked boundaries # ADR-WS-001: WebSocket 플랫폼은 leaf 하나 안의 패키지로 싣고, 경계는 기계로 검사한다
- Status: Superseded 2026-09-25 — the eighteen-package platform was cut to the parts a Spring - 상태: 대체됨 2026-09-25 — 패키지 열여덟 개짜리 플랫폼을 Spring 설정이나 실제 container lane이 닿는 부분으로 잘랐다: `stomp`
configuration or a real-container lane reaches: the `stomp` channel and the servlet handler 채널과 servlet handler 라이브러리(`servlet`, `outbound`, `budget`). Advanced 패키지, reactive runtime, `WebSocketArchitectureRules`
library (`servlet`, `outbound`, `budget`). The Advanced packages, the reactive runtime and the 묶음은 나머지와 함께 갔다(`docs/capability-status.md`를 본다).
`WebSocketArchitectureRules` pack went with the rest (see `docs/capability-status.md`). - 날짜: 2026-08-25
- Date: 2026-08-25 - 범위: `:adapter:inbound:websocket`
- Scope: `:adapter:inbound:websocket`
## Context ## 배경
The realtime connection platform design models itself as eighteen Gradle modules under 실시간 연결 플랫폼 설계는 스스로를 `modules/websocket` 아래 Gradle 모듈 열여덟 개로 모델링하고, 모듈마다 순수성 등급과 허용 의존
`modules/websocket`, each with a declared purity grade and a declared set of allowed dependencies. 집합을 선언한다. 이 저장소의 `src/config/architecture/modules.json`은 leaf 목록을 가진 실패하면 닫히는 registry다. leaf 열여덟 개를
This repository's `src/config/architecture/modules.json` is a fail-closed registry that owns the 더하는 것은 자기 결정이 필요한 크기의 registry 변경이고, HARD-STOP #5가 그것을 은근슬쩍 하는 것을 금지한다.
leaf list; adding eighteen leaves is a registry change of a size that needs its own decision, and
HARD-STOP #5 forbids doing it implicitly.
Three earlier platforms in this repository — JPA, GraphQL, and the HTTP platform — met the same 이 저장소의 앞선 플랫폼 셋 — JPA, GraphQL, HTTP 플랫폼 — 이 같은 상황을 만났고 같은 방식으로 풀었다.
situation and resolved it the same way.
## Decision ## 결정
The eighteen design modules ship as packages inside the single registered leaf. `WebSocketStableModule` 설계 모듈 열여덟 개를 등록된 leaf 하나 안의 패키지로 싣는다. `WebSocketStableModule`이 모듈마다 패키지, 순수성 등급, 정확한 허용
declares each one's package, purity grade and exact allowed edges, and `WebSocketModuleBoundaryTest` edge를 선언하고, `WebSocketModuleBoundaryTest`가 운영 트리를 scan해 선언과 트리가 어느 방향으로든 다르면 실패한다.
scans the production tree and fails when the declaration and the tree disagree in either direction.
Three deviations from the design's module map were forced by the check and are recorded in 검사가 강요한, 설계 모듈 지도와 다른 점 셋은 `docs/websocket/repository-adaptation.md`에 적었다: `WebSocketSubprotocolName`을
`docs/websocket/repository-adaptation.md`: `WebSocketSubprotocolName` moved to `core` and the codec `core`로 옮겼고 codec을 자기 FRAMEWORK_BOUND 모듈로 옮겼다. 둘 다 설계의 배치가 여기서 만든 순환을 피하려는 것이다. 그리고
moved to its own FRAMEWORK_BOUND module, both to avoid cycles the design's placement created here; `budget`이 `core`에서 아무것도 import하지 않으므로 `budget -> core` edge를 뒤집었다.
and the `budget -> core` edge was inverted because `budget` imports nothing from `core`.
## Consequences ## 결과
**The boundary is enforced, not documented.** Six violations were caught during implementation that **경계를 문서로 두지 않고 강제한다.** 구현 중에 문서라면 잡지 못했을 위반 여섯 개를 잡았다: 순환이 될 뻔한 것 둘, id 둘이 패키지
a document would not have: two would-be cycles, a duplicate module declaration where two ids claimed 하나를 주장한 중복 모듈 선언, 선언하지 않은 edge 셋. 배울 것이 있는 쪽은 중복이다 — 패키지 하나에 id가 둘이면 소유가 반복 순서에
one package, and three undeclared edges. The duplicate is the instructive one — with two ids on one 달리고 한 모듈의 규칙이 소리 없이 아무것에도 적용되지 않는다. 그것을 막는 guard가 이제 경계 시험의 일부다.
package, ownership depends on iteration order and one module's rules silently apply to nothing. A
guard against it is now part of the boundary test.
**The detector had a hole.** Its framework-import list named `com.fasterxml` (Jackson 2) and not **찾는 장치에 구멍이 있었다.** 그 프레임워크 import 목록은 `com.fasterxml`(Jackson 2)를 대고 Spring 7이 실제로 쓰는
`tools.jackson` (Jackson 3), which is what Spring 7 actually uses — so a CORE module could have `tools.jackson`(Jackson 3)을 대지 않았다 — 그래서 CORE 모듈이 mapper를 import해도 들키지 않을 수 있었다. 여기와, 그 목록을 같이 쓰던
imported a mapper unnoticed. Fixed here and in the HTTP platform, which shared the list. HTTP 플랫폼에서 고쳤다.
**Promotion stays cheap.** Each enum constant is already shaped like a leaf specification, so **승격은 싸게 남는다.** enum 상수 하나하나가 이미 leaf 명세 모양이라서, 나중에 하나를 떼어 내는 것은 고고학이 아니라 registry
splitting one out later is a registry edit rather than an archaeology exercise. 수정이다.
**The design's own rules were kept where they cost something.** `core` names no framework, so the **비용이 드는 곳에서도 설계 자신의 규칙을 지켰다.** `core`는 어떤 프레임워크도 이름으로 대지 않으므로 같은 결정이 두 runtime에
same decisions serve both runtimes and are testable without a server; no Java class name reaches the 쓰이고 서버 없이 시험할 수 있다. Java 클래스 이름이 wire에 닿지 않는다. payload는 map이 아니라 인코딩한 문자열이다. 그리고
wire; the payload is an encoded string rather than a map; and handlers are given no way to write, handler에게는 쓸 길을 주지 않는다. 그것이 순서와 backpressure를 관례가 아니라 보장으로 만든다.
which is what makes ordering and backpressure guarantees rather than conventions.
## Alternatives considered ## 따져 본 대안
**Register eighteen leaves.** Faithful to the design and a large change to a fail-closed registry **leaf 열여덟 개를 등록한다.** 설계에 충실하지만, 어느 쪽이든 artifact 하나로 싣는 플랫폼을 위해 실패하면 닫히는 registry를 크게
for a platform that ships as one artifact either way. Rejected as disproportionate; the boundary 바꾼다. 지나치다고 보고 버렸다. 경계 시험이 모듈이 주려던 성질을 준다.
test provides the property the modules were for.
**Ship the modules as packages with no enforcement.** Cheapest, and it makes the boundary a claim. **모듈을 강제 없는 패키지로 싣는다.** 가장 싸지만 경계를 주장으로 만든다. 구현 중에 찾은 위반 여섯 개가 그것에 반대하는 근거다.
The six violations found during implementation are the argument against it.
+39 -47
View File
@@ -8,64 +8,56 @@
- 대체됨: `docs/capability-status.md` - 대체됨: `docs/capability-status.md`
<!-- 머리 블록 끝 --> <!-- 머리 블록 끝 -->
# ADR-WS-002: Resume and cluster state are caches, and are treated as caches # ADR-WS-002: resume와 cluster 상태는 cache이고, cache로 다룬다
- Status: Superseded 2026-09-25 — `advanced.resume`, `advanced.cluster` and `advanced.presence` - 상태: 대체됨 2026-09-25 — `advanced.resume`, `advanced.cluster`, `advanced.presence`를 지웠다: 아무것도 그것을 조립하지
were removed: nothing assembled them (see `docs/capability-status.md`). 않았다(`docs/capability-status.md`를 본다).
- Date: 2026-08-25 - 날짜: 2026-08-25
- Scope: `adapter:inbound:websocket` — `advanced.resume`, `advanced.cluster`, `advanced.presence` - 범위: `adapter:inbound:websocket` — `advanced.resume`, `advanced.cluster`, `advanced.presence`
## Context ## 배경
Advanced Tasks 2–8 add three things that all look like state and are not: a resume token that says Advanced Task 2–8은 모두 상태처럼 보이지만 상태가 아닌 것 셋을 더한다: client가 어디까지 왔는지 말하는 resume token, 어느 노드가
where a client got to, a cluster index that says which node holds a session, and a presence summary 세션을 가졌는지 말하는 cluster index, 그 index에서 끌어낸 presence 요약.
derived from that index.
Each is a statement about the past. The resume token was minted before the disconnect; the index 하나하나가 과거에 대한 진술이다. resume token은 연결이 끊기기 전에 만들어졌다. index 항목은 그 뒤에 죽었을 수 있는 노드가 썼다.
entry was written by a node that may since have died; presence is a read of the index and inherits presence는 index를 읽은 것이고 그것의 틀린 점을 모두 물려받는다. 이 ADR이 막으려는 실패는 그중 어느 것이든 지금의 사실로 다루는
everything wrong with it. The failure this ADR exists to prevent is treating any of them as current 것이다. 부르는 자리에서는 하나같이 사실처럼 읽히기 때문이다.
fact, because each reads as one at the call site.
## Decision ## 결정
**Resume is bounded by what the replay store actually holds, not by what the token claims.** **resume은 token이 주장하는 것이 아니라 replay 저장소가 실제로 가진 것으로 묶는다.** `ResumeCoordinator`는 위치를 받아 주기 전에
`ResumeCoordinator` consults `ReplayAvailability` before honouring a position. A token that names a `ReplayAvailability`를 묻는다. 저장소가 이미 버린 위치를 대는 token은 빈틈을 메운 stream이 아니라 다시 맞추기를 낸다. 대안 — token을
position the store has evicted produces a resynchronise, not a gap-filled stream. The alternative — 믿기 — 은 구멍 난 stream을 소리 없이 전달하고, client가 그것이 완전하다고 믿으므로 명시적 다시 맞추기보다 나쁘다.
trusting the token — silently delivers a stream with a hole in it, which is worse than an explicit
resynchronise because the client believes it is complete.
**Cluster index entries carry an observation time and are checked against it on every read.** **cluster index 항목은 관찰 시각을 싣고, 읽을 때마다 그것과 대조한다.** `ExternalSessionSummary.staleAt`은 「index가 edge-2라고
`ExternalSessionSummary.staleAt` exists so that "the index says edge-2" cannot be used without also 한다」를 「언제 기준으로」에 답하지 않고는 쓸 수 없게 하려고 있다. 보고를 멈춘 노드의 항목은 그 노드가 세션을 가졌다는 증거가
answering "as of when". An entry whose node stopped reporting is not evidence that the node holds 아니다.
the session.
**Durable fan-out is deduplicated by stream position, not by message id.** At-least-once is the **durable fan-out의 중복은 message id가 아니라 stream 위치로 거른다.** 계약이 at-least-once이므로 재전달은 보통 동작이다: 재배포,
contract, so redelivery is normal operation: a redeploy, a slow consumer or a broker rebalance all 느린 소비자, broker rebalance가 모두 그것을 낳는다. `FanoutDeduplicator`는 `(stream, position)`을 키로 쓰고 `compute` 아래에서
produce it. `FanoutDeduplicator` keys on `(stream, position)` and advances a high-water mark under high-water mark를 올리므로, 소비자 스레드 둘이 같은 위치를 둘 다 전달할 수 없다.
`compute`, so two consumer threads cannot both deliver the same position.
**Presence has four states, not two.** `OFFLINE` is a reported fact; `STALE` is the absence of one. **presence에는 상태가 둘이 아니라 넷이다.** `OFFLINE`은 보고된 사실이고, `STALE`은 사실이 없는 것이다. 둘을 합치면 Redis partition
Collapsing them reports every user as disconnected during a Redis partition, when what happened is 동안 모든 사용자를 연결 끊김으로 알리는데, 실제로 일어난 일은 index가 어두워졌고 연결은 멀쩡한 것이다.
that the index went dark and the connections are fine.
**Nothing security-relevant may depend on presence.** An attacker who can make a node stop reporting **보안에 관련된 어떤 것도 presence에 기대면 안 된다.** 노드가 보고를 멈추게 할 수 있는 공격자는 누가 있는지에 대한 플랫폼의 믿음을
can move the platform's belief about who is present. Presence answers "show a green dot". 움직일 수 있다. presence는 「초록 점을 보여 줄까」에 답한다.
## Consequences ## 결과
- A resume that cannot be honoured is visible to the client as a resynchronise. Clients must - 받아 줄 수 없는 resume은 client에게 다시 맞추기로 보인다. client는 그것을 구현해야 한다. 플랫폼이 소리 없이 시늉하는 모드는 없다.
implement one; there is no mode in which the platform silently pretends. - cluster index를 읽을 때마다 시계가 필요하다. 일부러 둔 마찰이다.
- Every read of the cluster index needs a clock. This is deliberate friction. - `PresenceSummary.classify`는 stale 창 이상인 idle 창을 거절한다. 그렇지 않으면 `IDLE`에 닿을 수 없고, 호출자는 상태 셋짜리를
- `PresenceSummary.classify` refuses an idle window at or past the stale window, because otherwise 가지고 넷짜리 모델이라고 믿는다.
`IDLE` is unreachable and the caller believes it has a four-state model when it has three. - fan-out envelope은 한계 있는 참조와 catalog로 인코딩한 문서를 싣고, 업무 객체는 싣지 않는다. rolling deploy에서는 코드 두 버전이
- Fan-out envelopes carry a bounded reference and the catalog-encoded document, never a business 같은 envelope을 읽는다.
object. A rolling deploy has two versions of the code reading the same envelope.
## Alternatives considered ## 따져 본 대안
- **Trust the resume token.** Rejected: it makes a gap indistinguishable from a complete stream. - **resume token을 믿는다.** 버렸다: 빈틈을 완전한 stream과 구별할 수 없게 만든다.
- **Deduplicate by message id.** Rejected: a broker that redelivers may re-mint ids, and a producer - **message id로 중복을 거른다.** 버렸다: 재전달하는 broker는 id를 다시 만들 수 있고, 재시도하는 producer는 반드시 그렇게 한다.
that retries certainly does. Position is the property the ordering actually has. 위치가 순서가 실제로 가진 성질이다.
- **A single `online` boolean.** Rejected for the partition case above. - **`online` boolean 하나.** 위 partition 경우 때문에 버렸다.
- **Write presence separately from the session index.** Rejected: two sources of truth for "who is - **presence를 세션 index와 따로 쓴다.** 버렸다: 「누가 연결돼 있나」의 정본이 둘이면 어긋나고, 그 어긋남은 보이지 않는다 — 둘 다
connected" drift, and the drift is invisible — both look plausible and nothing reconciles them. 그럴듯해 보이고 아무것도 둘을 맞추지 않는다.
+45 -57
View File
@@ -8,78 +8,66 @@
- 대체됨: `docs/capability-status.md` - 대체됨: `docs/capability-status.md`
<!-- 머리 블록 끝 --> <!-- 머리 블록 끝 -->
# ADR-WS-003: STOMP is an Advanced adapter with a declared destination catalog # ADR-WS-003: STOMP는 destination catalog를 선언한 Advanced 어댑터다
- Status: Superseded 2026-09-25 — `advanced.stomp` and `advanced.stomp.rabbit` were removed; the - 상태: 대체됨 2026-09-25 — `advanced.stomp`와 `advanced.stomp.rabbit`을 지웠다. `stomp` 패키지가 유일한 STOMP 채널이다
`stomp` package is the only STOMP channel (see `docs/capability-status.md`). (`docs/capability-status.md`를 본다).
- Date: 2026-08-25 - 날짜: 2026-08-25
- Scope: `adapter:inbound:websocket` — `advanced.stomp`, `advanced.stomp.rabbit` - 범위: `adapter:inbound:websocket` — `advanced.stomp`, `advanced.stomp.rabbit`
## Context ## 배경
Advanced Tasks 9–13 add STOMP 1.2 alongside the platform's own protocol, plus a RabbitMQ broker Advanced Task 9–13은 플랫폼 자신의 프로토콜 옆에 STOMP 1.2를 더하고, RabbitMQ broker relay와 노드를 가로지르는 user destination도
relay and cross-node user destinations. 더한다.
This leaf already ships an older STOMP-over-SockJS channel (`stomp`, gated on 이 leaf는 이미 더 오래된 STOMP-over-SockJS 채널(`stomp`, `app.websocket.enabled`로 막는다)을 싣는다. 한 context 안의
`app.websocket.enabled`). Two `@EnableWebSocketMessageBroker` configurations in one context `@EnableWebSocketMessageBroker` 설정 둘은 시끄럽게 충돌하지 않는다 — 둘 다 configurer를 기여하고, 둘 다
do not conflict loudly — both contribute a configurer, both call `configureMessageBroker`, and the `configureMessageBroker`를 부르며, 결과 broker는 마지막에 돈 쪽의 것이다. 오류도 로그도 없다.
broker that results is whichever ran last. Nothing errors and nothing logs.
STOMP also brings a destination model that is a free string from the client. Without a catalog, the STOMP는 client에게서 오는 자유 문자열인 destination 모델도 가져온다. catalog가 없으면 닿을 수 있는 destination 집합은 broker가 받는
set of reachable destinations is whatever the broker accepts, which for the simple broker is every 모든 것이고, simple broker에게 그것은 모든 문자열이다.
string.
## Decision ## 결정
**The Advanced adapter is its own module (`advanced-stomp`), separate from `advanced`.** It is the **Advanced 어댑터는 `advanced`와 따로 둔 자기 모듈(`advanced-stomp`)이다.** 순수할 수 없는 유일한 Advanced capability다 — 여기서
one Advanced capability that cannot be pure — STOMP here *is* the Spring Messaging types — and STOMP는 곧 Spring Messaging 타입이다 — 그리고 `advanced`에 접어 넣으면 그 모듈의 모든 capability에 대해 순수성을 느슨하게 만든다.
folding it into `advanced` would relax that module's purity for every capability in it.
**The relay is a further module (`advanced-stomp-rabbit`).** The adapter parses a protocol; the **relay는 그다음 모듈(`advanced-stomp-rabbit`)이다.** 어댑터는 프로토콜을 파싱한다. relay는 남의 broker에 TCP 연결을 열고 모든
relay opens a TCP connection to somebody else's broker and makes every delivery depend on it. 전달을 그것에 기대게 만든다. 피해 범위가 다르고, 결정이 다르고, 모듈이 다르다.
Different blast radius, different decision, different module.
**Destinations are declared, per operation.** `StompDestinationCatalog` maps `(operation, **destination은 operation마다 선언한다.** `StompDestinationCatalog`는 `(operation, destination)`을 필요한 권한에 대응시킨다. 선언하지
destination)` to a required permission. Undeclared is refused. `SUBSCRIBE` and `SEND` are separate 않은 것은 거절한다. `SUBSCRIBE`와 `SEND`는 따로 선언한다. feed를 읽는 것과 거기에 게시하는 것은 다른 권리이기 때문이다.
declarations, because reading a feed and publishing into it are different rights.
**The authorization decision is a value, not an interceptor method.** `StompAuthorizationPolicy` **인가 판정은 interceptor 메서드가 아니라 값이다.** `StompAuthorizationPolicy`가 `StompAuthorizationDecision`을 돌려주고,
returns a `StompAuthorizationDecision`; `StompSecurityInterceptor` only extracts and enforces. A rule `StompSecurityInterceptor`는 꺼내서 강제하기만 한다. `MessageChannel`을 거쳐서만 닿는 규칙은 누가 channel을 만들어 둔 경우만
reachable only through a `MessageChannel` gets tested for the cases somebody built a channel for. 시험된다.
**Only one STOMP runtime may run.** `StompBrokerExclusivity` fails the context when both channels **STOMP runtime은 하나만 돌 수 있다.** `StompBrokerExclusivity`는 두 채널이 모두 켜졌을 때, 두 broker가 모두 켜졌을 때, 또는 뒤에
are enabled, when both brokers are, or when the adapter is enabled with no broker behind it. broker 없이 어댑터가 켜졌을 때 context를 실패시킨다.
**A `RECEIPT` is never promoted to a commit.** `StompEvidence` has six stages and **`RECEIPT`는 절대 커밋으로 올리지 않는다.** `StompEvidence`에는 단계가 여섯 있고 `StompAckPolicy.evidenceForReceipt()`는
`StompAckPolicy.evidenceForReceipt()` is fixed at `PROTOCOL_RECEIPT`. The receipt is written by the `PROTOCOL_RECEIPT`로 고정이다. receipt는 프로토콜 계층이 쓰고, 그 계층은 일이 성공했는지 아무것도 모른다.
protocol layer, which knows nothing about whether the work succeeded.
**The simple broker declares what it cannot do.** `SimpleBrokerProfile` cannot be constructed **simple broker는 할 수 없는 것을 선언한다.** `SimpleBrokerProfile`은 cluster 지원이나 durable ack를 주장하며 만들 수 없고,
claiming cluster support or durable acks, and refuses activation outside local/test — in a local·test 밖에서 켜기를 거절한다 — 여러 노드 배포에서 그것은 오류를 내지 않고, 게시한 노드에 있는 사용자 일부에게만 전달한다.
multi-node deployment it does not error, it delivers to whichever fraction of users is on the
publishing node.
**Unresolved user destinations are broadcast once and then dead-lettered.** **풀리지 않은 user destination은 한 번 broadcast한 뒤 dead-letter로 보낸다.** `MultiNodeUserDestination`은 broadcast를 *거쳐* 온
`MultiNodeUserDestination` distinguishes a message that arrived *via* the broadcast from one that did 메시지와 그렇지 않은 메시지를 구별한다. 그렇지 않으면 모든 노드가 풀 수 없는 메시지를 받을 때마다 다시 broadcast한다.
not. Without that, every node rebroadcasts every unresolvable message on receipt.
## Consequences ## 결과
- Enabling Advanced STOMP requires disabling the legacy channel. There is no migration path that - Advanced STOMP를 켜려면 옛 채널을 꺼야 한다. 둘을 함께 돌리는 옮기기 길은 없다. 배타성 검사가 그것을 새벽 3시가 아니라 기동
runs both; the exclusivity check makes that explicit at startup rather than at 3am. 때 분명히 한다.
- A deployment must write its own catalog. There is deliberately no default: an empty one refuses - 배포는 자기 catalog를 써야 한다. 일부러 기본값이 없다: 빈 catalog는 모든 frame을 거절해서 고장 난 어댑터처럼 읽히고, 비어 있지
every frame and reads as a broken adapter, and a non-empty one publishes destinations nobody chose. 않은 기본 catalog는 아무도 고르지 않은 destination을 게시한다.
- The relay's cost is one broker connection per authenticated session plus one system connection. - relay의 비용은 인증된 세션마다 broker 연결 하나 + 시스템 연결 하나다. `brokerConnectionsFor`는 첫 장애 전에 그것을 계산하려고
`brokerConnectionsFor` exists so this is computed before the first outage. 있다.
- User-destination metrics are tagged with `UserDestinationAction`, never the destination — a user - user destination metric은 destination이 아니라 `UserDestinationAction`으로 tag를 단다 — user destination은 구조상 사용자 식별자를
destination contains a user identifier by construction. 담는다.
## Alternatives considered ## 따져 본 대안
- **Extend the existing `stomp` package.** Rejected: it is Stable, and WS-ARCH-6 forbids a Stable - **기존 `stomp` 패키지를 넓힌다.** 버렸다: 그것은 Stable이고, WS-ARCH-6은 Stable 모듈이 Advanced 모듈 이름을 대는 것을 금지한다.
module naming an Advanced one. Making the legacy channel profile-driven would have required that 옛 채널을 profile로 움직이게 하려면 그 edge가 필요했다.
edge. - **relay를 포함한 `advanced-stomp` 모듈 하나.** 버렸다: relay는 따로 정할 운영 결정이고, 그것만 따로 거절할 수 있어야 한다.
- **One `advanced-stomp` module including the relay.** Rejected: the relay is a separate operational - **wildcard 권한으로 선언하지 않은 destination을 허용한다.** 버렸다: wildcard가 기본이 되고 catalog는 문서가 된다.
decision and deserves to be refusable on its own.
- **Allow undeclared destinations with a wildcard permission.** Rejected: the wildcard becomes the
default and the catalog becomes documentation.
@@ -0,0 +1,34 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-08-14
- 요약: 알림 submit()은 영속적으로 받아들였다는 뜻이라는 결정이다.
- 현재 정본: `docs/notification/support-matrix.md`
<!-- 머리 블록 끝 -->
# NOTIF-ADR-001 — `submit()`은 durable 접수를 뜻한다
## 상태
채택.
## 배경
알림 플랫폼의 뻔한 API는 성공이나 실패를 돌려주는 `send()`다. 이 플랫폼이 지원하는 모든 채널이 그 반환값을 거짓말로 만든다:
- SES는 요청을 받고 `MessageId`를 돌려준 뒤에도 보내기를 거절할 수 있다.
- Twilio는 `accepted`, `sent`, `delivered`를 따로따로, 나중에 오는 이벤트로 나눈다.
- APNs는 알림을 받은 뒤 전달하거나, 저장하거나, 버릴 수 있다.
- Web Push는 프로토콜 수준에서 push service의 접수와 user agent의 확인 응답을 나눈다.
## 결정
`submit()`과 `schedule()`은 논리 요청과 그 수신자 job이 데이터베이스에 커밋되면 돌아온다. 접수증은 `notificationId`,
`RequestStatus`, `acceptedAt`을 싣고, `delivered`·`sent`·`read` 요소가 없다. 트랜잭션이 열려 있는 동안에는 어떤 provider에도
연락하지 않는다.
## 결과
타입이 그렇게 읽을 길을 주지 않으므로, 호출자는 접수를 전달로 착각할 수 없다. 전달 상태는 provider 이벤트 원장에서 만든
projection에 대한 따로 둔 query다. 비용은 「도착했나?」가 두 번째 질문이라는 것이다 — 그것이 정직한 질문 수다.
@@ -0,0 +1,31 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-08-14
- 요약: 알림 상태를 덧붙이기만 하는 이벤트 원장과 채널별 projector로 둔다는 결정이다.
- 현재 정본: `docs/notification/support-matrix.md`
<!-- 머리 블록 끝 -->
# NOTIF-ADR-002 — 채널 projector를 둔 append-only 이벤트 원장
## 상태
채택.
## 배경
선형 전달 상태 하나는 제자리에서 고쳐야 하고, 그러면 새 이벤트가 저장된 것보다 앞서는지 정할 규칙이 필요하다. 자연스러운 규칙 —
ordinal 비교 — 은 실제 provider traffic에서 틀린다. Twilio는 callback 순서를 보장하지 않아서 `sent`가 `delivered` 뒤에 온다. email은
전달 뒤에 불만 신고를 낸다. 두 경우 모두 ordinal 규칙 아래에서 정보를 잃는다.
## 결정
provider 이벤트는 어떤 projection이 돌기 전에 바뀌지 않는 원장에 덧붙인다. 채널별 projector가 명시한 전이 표로 이벤트를
`SubmissionOutcome`, `DeliveryOutcome`, `EvidenceLevel`, `EngagementFacts`, `SuppressionFacts`로 합친다. projection은 멱등이고 원장에서
다시 돌릴 수 있다.
## 결과
중복, 순서가 뒤바뀐, 늦은 이벤트는 결함이 아니라 보통 입력이다. 잘못 project한 이벤트가 아직 저장돼 있으므로 projector 결함은
회복할 수 있다. projector 버전은 다시 돌려서 옮길 수 있다. 비용은 이벤트마다 두 번째 쓰기와, 원장보다 늦을 수 있는 projection이다.
@@ -0,0 +1,42 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-08-14
- 요약: 결과가 모호한 제출을 정식 상태로 둔다는 결정이다.
- 현재 정본: `docs/notification/support-matrix.md`
<!-- 머리 블록 끝 -->
# NOTIF-ADR-003 — 모호한 제출은 정식 상태다
## 상태
채택.
## 배경
가장 흔한 심각한 실패는 거절이 아니다. body는 provider에 닿았는데 응답이 돌아오지 않은 요청이다. 플랫폼에는 provider 요청 id가 없고,
사용자는 알림을 받았을 수도 안 받았을 수도 있다.
그것을 실패로 다루면 중복이 생긴다: 재시도가 두 번째 메시지를 보내고, 채널을 넘는 대체가 이미 도착한 push 옆에 SMS를 보낸다. 성공으로
다루면 실제 실패를 잃는다.
## 결정
`AMBIGUOUS`는 저장되는 `SubmissionOutcome`이자 `AttemptConfirmation`이다. 시도는 `requestStarted`, `requestBodyCommitted`,
`providerResponseReceived`를 기록하고, 각각 `PROVEN`, `INFERRED`, `UNKNOWN` 중 하나의 `EvidenceCertainty`를 가진다. 그래서 모르는
어댑터가 `false`로 답하도록 강요받지 않는다.
수신자 전달에 모호한 시도가 있는 동안에는:
- provider가 요청별 멱등성을 증명하지 않으면 자동 재시도를 막는다
- 채널을 넘는 자동 대체는 조건 없이 막는다
- provider가 상태 query를 지원하면 맞춰 보기를 돌린다
- 그렇지 않으면 전달을 멈추고 운영자를 기다린다
모호한 시도를 운영자가 다시 보내려면 중복 위험을 명시해 승인해야 한다.
## 결과
어떤 알림은 사람이나 맞춰 보기 한 바퀴가 필요한 상태에서 멈춘다. 그것이 의도한 거래다: 풀리지 않은 모름이 보장된 중복보다 싸고,
상태는 어느 쪽으로든 소리 없이 풀리지 않고 보인다.
+33
View File
@@ -0,0 +1,33 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-08-14
- 요약: FCM 대상은 installation id를 먼저 쓴다는 결정이다.
- 현재 정본: `docs/notification/provider-runbooks.md`
<!-- 머리 블록 끝 -->
# NOTIF-ADR-004 — FCM installation id가 주 대상이다
## 상태
채택.
## 배경
Firebase는 이제 installation id(FID)를 권하고 registration token multicast 경로를 옛것으로 다룬다. `token` 문자열 하나 위에 세운
contact point 모델은 옛 모델을 유일한 것으로 담게 되고, 나중의 옮기기는 런타임 해석 문제가 된다: 같은 문자열 필드가 행마다 다른
뜻이 된다.
## 결정
`MobilePushTarget`은 `FcmInstallationId`, `LegacyFcmRegistrationToken`, `ApnsDeviceToken`으로 된 sealed 계층이다. 종류는 문자열 필드
하나의 구분자가 아니라 따로 둔 타입이고, 각각 자기 `ContactPointType`을 싣는다. 그래서 유일성 범위와 암호화 associated data가 다르다.
APNs token은 환경도 싣는다. sandbox와 production은 flag가 아니라 따로 둔 namespace이기 때문이다.
## 결과
대상 종류를 옮기는 것은 런타임 짐작이 아니라 빠짐없는 `switch`를 쓴 컴파일 시점 변경이다. 어댑터가 종류마다 자기 wire 표현으로
대응시키므로, provider가 한 경로를 바꿔도 다른 경로가 소리 없이 바뀌지 않는다. 비용은 문자열 필드보다 타입이 하나 더 필요하다는
것이다.
@@ -11,7 +11,7 @@
## 상태 ## 상태
Accepted (2026-08-15). NTF-018 대응. 채택(2026-08-15). NTF-018 대응.
**갱신 (2026-09-25):** R1 type은 삭제됐다. production consumer가 끝까지 0건이었고 fake로만 증명된 **갱신 (2026-09-25):** R1 type은 삭제됐다. production consumer가 끝까지 0건이었고 fake로만 증명된
계약이라, 새 consumer를 막는 ArchUnit 규칙을 유지할 이유가 없어졌다. 남은 것은 adapter core의 계약이라, 새 consumer를 막는 ArchUnit 규칙을 유지할 이유가 없어졌다. 남은 것은 adapter core의
@@ -47,9 +47,10 @@ bridge도 import도 없다.
reconciliation을 실제 PostgreSQL 레인으로 증명한다(NOTIF-ADR-001~003). R1은 fake로 증명된 R1 계약이며 reconciliation을 실제 PostgreSQL 레인으로 증명한다(NOTIF-ADR-001~003). R1은 fake로 증명된 R1 계약이며
스스로 그렇게 선언한다 — `application-core/CLAUDE.md`가 "R1 application contract proven with fakes. 스스로 그렇게 선언한다 — `application-core/CLAUDE.md`가 "R1 application contract proven with fakes.
It does not claim PostgreSQL schema/locking, provider protocol, cryptographic verifier, or runtime It does not claim PostgreSQL schema/locking, provider protocol, cryptographic verifier, or runtime
wiring qualification"이라고 적어 둔 그대로다. wiring qualification"(fake로 증명한 R1 애플리케이션 계약이다. PostgreSQL schema·locking, provider 프로토콜, 암호
검증기, 런타임 배선 검증은 주장하지 않는다)이라고 적어 둔 그대로다.
## Disposition ## 처분
R1 public type 100개의 처분은 네 가지 중 하나다. R1 public type 100개의 처분은 네 가지 중 하나다.
@@ -1,60 +1,55 @@
# gRPC advanced capability support matrix # gRPC advanced capability 지원 매트릭스
Every capability in `:grpc-advanced:*`, its grade, and what it would take to raise it. `:grpc-advanced:*`의 모든 capability, 그 등급, 그리고 등급을 올리는 데 필요한 것이다. 기본 등급의 정본은
`GrpcAdvancedSupportMatrix` is the machine-readable form; `GrpcAdvancedCapability.defaultGrade` `GrpcAdvancedCapability.defaultGrade`다. 근거가 있는 배포는 `GrpcAdvancedFeatureFlags.withGrade`로 바꾼다.
carries the same values.
All capabilities are off by default. Flags are `app.grpc.advanced.<capability>.enabled`. capability는 모두 기본으로 꺼져 있다. 스위치는 `app.grpc.advanced.<capability>.enabled`다.
## Grades ## 등급
| Grade | May start | Production needs a separate approval | | 등급 | 뜰 수 있나 | 운영에 별도 승인이 필요한가 |
| --- | --- | --- | | --- | --- | --- |
| `ADVANCED_STABLE` | Yes | No | | `ADVANCED_STABLE` | 예 | 아니요 |
| `EXPERIMENTAL` | Yes | Yes | | `EXPERIMENTAL` | 예 | 예 |
| `WATCH` | No | — | | `WATCH` | 아니요 | — |
| `DISABLED` | No | — | | `DISABLED` | 아니요 | — |
## Capabilities ## capability
| Capability | Flag | Grade | Real infrastructure its evidence needs | | capability | 스위치 | 등급 | 증거에 필요한 실제 인프라 |
| --- | --- | --- | --- | | --- | --- | --- | --- |
| Protobuf Edition 2024 | `edition-2024` | `ADVANCED_STABLE` | — | | Protobuf Edition 2024 | `edition-2024` | `ADVANCED_STABLE` | — |
| Protobuf Edition 2026 | `edition-2026` | `WATCH` | — | | Protobuf Edition 2026 | `edition-2026` | `WATCH` | — |
| Client streaming | `client-streaming` | `ADVANCED_STABLE` | — | | client streaming | `client-streaming` | `ADVANCED_STABLE` | — |
| Bidirectional streaming | `bidi-streaming` | `ADVANCED_STABLE` | — | | bidirectional streaming | `bidi-streaming` | `ADVANCED_STABLE` | — |
| Manual flow control | `manual-flow-control` | `ADVANCED_STABLE` | — | | 수동 flow control | `manual-flow-control` | `ADVANCED_STABLE` | — |
| Read-only unary hedging | `hedging` | `EXPERIMENTAL` | — | | 읽기 전용 unary hedging | `hedging` | `EXPERIMENTAL` | — |
| Custom name resolver | `custom-resolver` | `ADVANCED_STABLE` | — | | 사용자 정의 name resolver | `custom-resolver` | `ADVANCED_STABLE` | — |
| Custom load balancer | `custom-load-balancer` | `EXPERIMENTAL` | — | | 사용자 정의 load balancer | `custom-load-balancer` | `EXPERIMENTAL` | — |
| Proxyless xDS | `xds` | `EXPERIMENTAL` | xDS control plane | | proxyless xDS | `xds` | `EXPERIMENTAL` | xDS control plane |
| gRPC-Web | `grpc-web` | `ADVANCED_STABLE` | gRPC-Web proxy | | gRPC-Web | `grpc-web` | `ADVANCED_STABLE` | gRPC-Web proxy |
| Servlet HTTP/2 | `servlet-compat` | `ADVANCED_STABLE` (flag only; no Servlet transport code since 2026-09-25) | Servlet container | | Servlet HTTP/2 | `servlet-compat` | `ADVANCED_STABLE`(스위치만 있다. 2026-09-25부터 Servlet 전송 코드가 없다) | Servlet 컨테이너 |
| Spring Integration bridge | `integration-bridge` | `ADVANCED_STABLE` | — | | Spring Integration bridge | `integration-bridge` | `ADVANCED_STABLE` | — |
| Reactor adapter | `reactor` | `ADVANCED_STABLE` | — | | Reactor 어댑터 | `reactor` | `ADVANCED_STABLE` | — |
| Kotlin coroutine / Flow | `kotlin` | `ADVANCED_STABLE` | Kotlin toolchain | | Kotlin coroutine / Flow | `kotlin` | `ADVANCED_STABLE` | Kotlin toolchain |
| Channelz / CSDS diagnostics | `channel-diagnostics` | `ADVANCED_STABLE` | — | | Channelz / CSDS 진단 | `channel-diagnostics` | `ADVANCED_STABLE` | — |
## What the grades mean here, concretely ## 여기서 등급이 구체적으로 뜻하는 것
**Grade is a statement about the contract, not about a deployment.** Every capability's contract is **등급은 배포가 아니라 계약에 대한 말이다.** 모든 capability의 계약은 이 저장소에서 구현되고 시험됐다. 실제 배포에서 나온
implemented and tested in this repository. What no capability has is evidence from a real deployment: 증거는 어느 capability에도 없고, 승격된 것도 없다.
`GrpcAdvancedPromotionEvidence` for each one is empty, and no promotion has been granted.
**Four capabilities cannot produce meaningful evidence here at all**, because the infrastructure they **capability 넷은 여기서 의미 있는 증거를 아예 낼 수 없다.** 필요한 인프라(gRPC-Web proxy, Servlet 컨테이너, xDS control
need is absent (gRPC-Web proxy, Servlet container, xDS control plane, Kotlin toolchain), and a suite plane, Kotlin toolchain)가 없고, 인프라 없이 돈 suite는 통과해도 아무것도 세우지 않기 때문이다.
that runs without its infrastructure passes and establishes nothing.
**Kotlin is the sharpest case.** This repository has no Kotlin toolchain, so Kotlin is not **Kotlin이 가장 날카로운 경우다.** 이 저장소에는 Kotlin toolchain이 없으므로 그것이 생기기 전까지 Kotlin은 여기서 지원할 수
supportable here until one exists. Only the Java-side coroutine cancellation bridge 없다. Java 쪽 coroutine 취소 bridge(`GrpcCoroutineContextBridge`)만 구현되고 시험됐다. 컴파일 lane은 없다.
(`GrpcCoroutineContextBridge`) is implemented and tested; there is no compile lane.
## Promotion thresholds ## 승격 기준
| To | Soak | Also required | | 목표 | soak | 그 밖에 필요한 것 |
| --- | --- | --- | | --- | --- | --- |
| `ADVANCED_STABLE` | 7 days | compatibility evidence, security review, fault evidence, performance evidence, ADR, runbook, real-environment test | | `ADVANCED_STABLE` | 7일 | 호환성 증거, 보안 리뷰, 장애 증거, 성능 증거, ADR, runbook, 실제 환경 시험 |
| Stable default | 30 days | all of the above, plus a dependency, security and operational-cost review | | Stable 기본값 | 30일 | 위의 모두와 의존성·보안·운영 비용 리뷰 |
`WATCH` becomes `EXPERIMENTAL` before anything else. Promotions are independent: promoting one `WATCH`는 무엇보다 먼저 `EXPERIMENTAL`이 된다. 승격은 서로 독립이다. 한 capability를 올려도 다른 것의 등급은 바뀌지 않는다.
capability changes no other's grade.
+48 -51
View File
@@ -1,77 +1,74 @@
# gRPC platform support matrix # gRPC 플랫폼 지원 매트릭스
What the Stable gRPC platform (`:grpc:*`) is certified against, what it is only checked against, and Stable gRPC 플랫폼(`:grpc:*`)이 무엇에 대해 인증됐고, 무엇에 대해서는 확인만 하고, 무엇은 지켜보기만 하는지다. 그 구별이
what is merely watched. The distinction is the point: "works with Spring Boot" is not a statement 요점이다. 「Spring Boot와 동작한다」는 누구도 행동에 옮길 수 없는 말이다.
anyone can act on.
The release gate is the `grpc-stable-release-gate` job in `.github/workflows/release.yml`: each 릴리스 gate는 `.github/workflows/release.yml`의 `grpc-stable-release-gate` job이다. 인증된 lane마다 아무것도 돌리지 않으면
certified lane is a strict test lane that fails when it runs nothing. The in-code 실패하는 strict test lane이다.
`GrpcCompatibilityMatrix`/`GrpcStableReleaseGate` pair was removed (review 2026-09-24 S5-lead-4):
no production or build code called it, so it gated nothing.
## Lanes > 이력: 코드 안의 `GrpcCompatibilityMatrix`/`GrpcStableReleaseGate` 짝은 지웠다(리뷰 2026-09-24 S5-lead-4). 운영 코드도 빌드
> 코드도 그것을 부르지 않아서 아무것도 막지 않았다.
| Lane | Grade | Failure blocks a release | ## lane
| lane | 등급 | 실패하면 릴리스를 막나 |
| --- | --- | --- | | --- | --- | --- |
| Boot-managed platform (Spring Boot 4.0.8 BOM) | Certified | Yes | | Boot가 관리하는 플랫폼(저장소의 Spring Boot BOM) | Certified | 예 |
| proto3 with explicit `optional` | Certified | Yes | | 명시적 `optional`을 쓰는 proto3 | Certified | 예 |
| `grpc-netty-shaded` | Certified | Yes | | `grpc-netty-shaded` | Certified | 예 |
| `grpc-netty` (unshaded) | Compatibility | No | | `grpc-netty`(shade하지 않음) | Compatibility | 아니요 |
| Upstream gRPC Java version override | Compatibility | No | | upstream gRPC Java 버전 override | Compatibility | 아니요 |
| Protobuf Edition 2024 | Watch | No | | Protobuf Edition 2024 | Watch | 아니요 |
| Protobuf Edition 2026 | Watch | No | | Protobuf Edition 2026 | Watch | 아니요 |
## Runtime baseline ## 런타임 기준선
| | | | | |
| --- | --- | | --- | --- |
| Java | 21 | | Java | 21 |
| Spring Boot | 4.0.8 (the repository baseline; the plans assume 4.1) | | Spring Boot | 저장소 기준선, `src/gradle/libs.versions.toml`(계획은 4.1을 가정한다) |
| io.grpc | `ext.grpcVersion` in `src/build.gradle` | | io.grpc | `src/gradle/libs.versions.toml`의 `grpc`. `GrpcPlatformModuleConventionPlugin`이 그 BOM을 모듈 범위로 import한다 |
| Protobuf | `ext.protobufVersion` in `src/build.gradle` | | Protobuf | `src/gradle/libs.versions.toml`의 protobuf 항목(어느 leaf가 어느 것을 쓰는지는 그 파일의 주석이 적는다) |
| Stable transport | Netty (shaded) | | Stable 전송 | Netty(shaded) |
| Stable RPC shapes | Unary, Server Streaming | | Stable RPC 모양 | Unary, Server Streaming |
| Stable resolvers | Static, DNS, Unix domain socket | | Stable resolver | Static, DNS, Unix domain socket |
| Stable load balancing | `pick_first`, `round_robin` | | Stable load balancing | `pick_first`, `round_robin` |
## Evidence grades ## 증거 등급
A capability may only be advertised on evidence of a grade that can establish it. capability는 그것을 세울 수 있는 등급의 증거로만 광고한다. `GrpcEvidenceGrade.requireCertifies`가 이것을 강제하고,
`GrpcEvidenceGrade.requireCertifies` enforces this, and `GrpcReleaseEvidence.supports` refuses a `GrpcReleaseEvidence.supports`가 맞지 않는 lane이 뒷받침하는 주장을 거부한다.
claim backed by the wrong lane.
| Grade | Lane | Establishes | | 등급 | lane | 세우는 것 |
| --- | --- | --- | | --- | --- | --- |
| `CONTRACT` | `grpcInProcessContractTest` | adapter, interceptor order, status mapping, validation, idempotency replay, context propagation | | `CONTRACT` | `grpcInProcessContractTest` | 어댑터, interceptor 순서, 상태 매핑, 검증, 멱등 replay, context 전파 |
| `TRANSPORT` | `grpcNettyContractTest` | HTTP/2, TLS, mTLS, metadata limit, message limit, GOAWAY, keepalive, graceful shutdown | | `TRANSPORT` | `grpcNettyContractTest` | HTTP/2, TLS, mTLS, metadata 한도, 메시지 한도, GOAWAY, keepalive, graceful shutdown |
| `FAULT` | `grpcFaultTest` | connection loss, completion unknown, partial stream, evidence classifier | | `FAULT` | `grpcFaultTest` | 연결 끊김, 완료 모름, 부분 stream, 증거 분류기 |
| `PERFORMANCE` | `grpcPerformanceTest` | latency, stream saturation, executor saturation, drain budget | | `PERFORMANCE` | `grpcPerformanceTest` | 지연, stream 포화, executor 포화, drain 예산 |
In-process results are never transport evidence. The in-process transport does not negotiate TLS, in-process 결과는 절대 전송 증거가 아니다. in-process 전송은 TLS를 협상하지 않고, HTTP/2 frame을 만들지 않고, 전송 수준 한도를
does not frame HTTP/2 and does not enforce transport-level limits, so a suite that passes there has 강제하지 않는다. 그래서 거기서 통과한 suite는 전송이 아니라 어댑터를 시험한 것이다.
tested the adapter and not the transport.
## What is not supported ## 지원하지 않는 것
| | Where it lives | | | 있는 곳 |
| --- | --- | | --- | --- |
| Client streaming, bidirectional streaming | `grpc-advanced` (`streaming`) | | client streaming, bidirectional streaming | `grpc-advanced` (`streaming`) |
| Manual flow control | `grpc-advanced` (`streaming`) | | 수동 flow control | `grpc-advanced` (`streaming`) |
| Hedging | `grpc-advanced` (`resilience`) | | Hedging | `grpc-advanced` (`resilience`) |
| Custom name resolver, custom load balancer | `grpc-advanced` (`resilience`) | | 사용자 정의 name resolver, 사용자 정의 load balancer | `grpc-advanced` (`resilience`) |
| xDS | `grpc-advanced` (`resilience`) | | xDS | `grpc-advanced` (`resilience`) |
| gRPC-Web, Servlet HTTP/2, Spring Integration, Reactor, Kotlin | `grpc-advanced-compat` | | gRPC-Web, Servlet HTTP/2, Spring Integration, Reactor, Kotlin | `grpc-advanced-compat` |
| Channelz / CSDS diagnostics | `grpc-advanced` (`diagnostics`) | | Channelz / CSDS 진단 | `grpc-advanced` (`diagnostics`) |
## Current release status ## 지금 릴리스 상태
Not released. Every `:grpc:*` leaf is `runtime_memberships: []` in the module registry, so the 릴리스하지 않았다. registry에서 모든 `:grpc:*` leaf는 `"build": "optional-grpc"`라 주 빌드 밖에 있고 어느 조립에도 들어가지
platform is build-only: it compiles, its lanes run, and no deployed artifact carries it. 않는다. 플랫폼은 빌드만 된다. 컴파일되고 lane이 돌지만, 배포되는 산출물 어디에도 실리지 않는다.
Two release gate inputs are outstanding and are the work between here and a release: 릴리스 gate 입력 둘이 남아 있고, 그것이 지금부터 릴리스까지의 일이다.
- **Performance baseline.** The performance lane runs and asserts shape — ordered percentiles, a gate - **성능 기준선.** 성능 lane은 돌고, 절대 수치가 아니라 모양을 단언한다. 순서 있는 백분위수와 그것을 읽는 gate다. 알려진
that reads them — rather than absolute numbers. A recorded baseline on a known runner is what turns runner에서 기록한 기준선이 생겨야 회귀 gate가 된다.
it into a regression gate. - **schema codegen.** 이 빌드에서는 `protoc`가 돌지 않는다(ADR-GRPC-002). 그래서 descriptor 산출물과 consumer-compile fixture는
- **Schema codegen.** No `protoc` runs in this build (ADR-GRPC-002), so the descriptor artifact and 컴파일한 schema에서 만들어지지 않고 정책으로 다스린다.
the consumer-compile fixture are governed as policy rather than produced from a compiled schema.
+138 -145
View File
@@ -1,209 +1,202 @@
# Fileserver configuration # Fileserver 설정
Every key below lives under `app.fileserver-platform` (environment form 아래 key는 모두 `app.fileserver-platform` 아래에 있다(환경 변수 형태는 `APP_FILESERVER_PLATFORM_*`).
`APP_FILESERVER_PLATFORM_*`).
While `app.fileserver-platform.enabled` is false none of these keys is bound at all — the `app.fileserver-platform.enabled`가 false인 동안에는 이 key들을 아예 바인딩하지 않는다. 바인딩하는
auto-configuration that binds them is not processed — so a malformed value in a block nobody auto-configuration이 처리되지 않기 때문이다. 그래서 아무도 켜지 않은 블록의 잘못된 값이 시작을 실패시키지
enabled cannot fail a startup. Once enabled, binding is strict: an unknown key under the prefix is 않는다. 켜면 바인딩은 엄격하다. 접두사 아래의 모르는 key는 무시하지 않고 거부한다. 기본값은 보수적인 쪽이다.
refused rather than ignored. The defaults are the conservative ones: the
admin plane is off, background reclamation is on (leaving it off is what fills the volume), copies
and moves may only target the default namespace, and there is no permissive authorization fallback. Turning the capability on is a deliberate act, and so is every surface it
exposes.
## Minimum to start - admin plane은 꺼져 있다.
- 백그라운드 회수는 켜져 있다(꺼 두면 volume이 찬다).
- copy와 move는 기본 namespace로만 쓸 수 있다.
- 권한을 느슨하게 풀어 주는 대체 경로는 없다.
capability를 켜는 것은 의도한 행동이고, 그것이 여는 면 하나하나도 그렇다.
## 시작에 필요한 최소 설정
```yaml ```yaml
app: app:
fileserver-platform: fileserver-platform:
enabled: true enabled: true
instance-id: ${HOSTNAME} # writer-lease owner; must be unique per node instance-id: ${HOSTNAME} # writer lease 소유자. 노드마다 달라야 한다
storage: storage:
root: /var/lib/backend/files # absolute, outside any webroot or config dir root: /var/lib/backend/files # 절대 경로. webroot·설정 폴더 밖
security: security:
access-policy: role-based # or supply your own FileAccessPolicyPort bean access-policy: role-based # 또는 직접 만든 FileAccessPolicyPort bean
observability: observability:
fingerprint-key: ${FILESERVER_FINGERPRINT_KEY} fingerprint-key: ${FILESERVER_FINGERPRINT_KEY}
``` ```
Startup fails, rather than degrading, when any of these is missing or unsafe: 아래 중 하나라도 빠지거나 안전하지 않으면 기능을 줄여 돌지 않고 시작이 실패한다.
| Condition | Why it is fatal | | 조건 | 왜 치명적인가 |
| --- | --- | | --- | --- |
| `security.access-policy` left at `required` with no `FileAccessPolicyPort` bean | a file capability that authorizes by default is worse than one that refuses to start | | `security.access-policy`가 `required`로 남았는데 `FileAccessPolicyPort` bean이 없다 | 기본으로 허락하는 파일 capability는 시작을 거부하는 것보다 나쁘다 |
| `observability.fingerprint-key` unset while metrics are on | an unkeyed digest of an enumerable identifier is reversible | | metric이 켜졌는데 `observability.fingerprint-key`가 없다 | 셀 수 있는 식별자를 key 없이 digest하면 되돌릴 수 있다 |
| the storage root fails a mandatory capability probe | a volume that cannot create atomically, keep staging and content on one FileStore, or refuse symlinks is unsafe, not degraded | | 저장 루트가 필수 capability probe를 통과하지 못한다 | 원자적으로 만들지 못하거나, staging과 content를 한 FileStore에 두지 못하거나, symlink를 거부하지 못하는 volume은 기능이 줄어든 것이 아니라 안전하지 않은 것이다 |
| `storage.publish-mode: atomic-move-required` on a volume where the probe could not prove an atomic move | the configured guarantee cannot be delivered | | probe가 원자적 move를 증명하지 못한 volume에 `storage.publish-mode: atomic-move-required` | 설정한 보장을 지킬 수 없다 |
| `security.access-policy: unenforced` under a `prod` profile | a value that was convenient in development must not survive promotion | | `prod` profile에서 `security.access-policy: unenforced` | 개발 때 편했던 값이 승격까지 살아남으면 안 된다 |
## Authorization — `security` ## 권한 — `security`
| Key | Default | Meaning | | Key | 기본값 | 뜻 |
| --- | --- | --- | | --- | --- | --- |
| `access-policy` | `required` | `required` (supply your own bean), `role-based`, or `unenforced` | | `access-policy` | `required` | `required`(bean을 직접 준다), `role-based`, `unenforced` |
| `read-roles` | `ROLE_FILE_READ` | grants metadata read and download | | `read-roles` | `ROLE_FILE_READ` | metadata 읽기와 다운로드를 허락한다 |
| `write-roles` | `ROLE_FILE_WRITE` | grants create, append, finalize, delete, copy, move | | `write-roles` | `ROLE_FILE_WRITE` | create, append, finalize, delete, copy, move를 허락한다 |
| `admin-roles` | `ROLE_FILE_ADMIN` | grants reverify and force-delete, and gates `/internal/fileserver/**` at the servlet chain | | `admin-roles` | `ROLE_FILE_ADMIN` | reverify와 force-delete를 허락하고, servlet chain에서 `/internal/fileserver/**`를 막는다 |
These roles decide the tier inside each operation. In front of it, every operation's use case 이 role들은 각 연산 안에서 등급(tier)을 정한다. 그 앞에서는 연산마다 use case가 `file:*` 권한을 가지고,
carries a `file:*` permission that the web adapter's method security checks against web 어댑터의 method security가 그 권한을 `app.authz.role-permissions`와 대조한다. `security.yml`은
`app.authz.role-permissions`; `security.yml` grants `file:read` to `ROLE_FILE_READ`, `file:read`를 `ROLE_FILE_READ`에, `file:upload`·`file:delete`·`file:copy`·`file:move`를 `ROLE_FILE_WRITE`에,
`file:upload`, `file:delete`, `file:copy` and `file:move` to `ROLE_FILE_WRITE`, and `file:admin` to `file:admin`을 `ROLE_FILE_ADMIN`에 준다. 여기서 등급 role의 이름을 바꾸면 거기서도 새 이름을 대응시켜야
`ROLE_FILE_ADMIN`. Renaming a tier role here means mapping the new name there as well, or the 한다. 아니면 등급을 보기도 전에 호출자가 거부된다(`docs/fileserver/design-deviations.md` §5).
caller is refused before the tier is consulted (`docs/fileserver/design-deviations.md` §5).
There is no anonymous-read switch. Every Fileserver route is authenticated by the servlet chain 익명 읽기 스위치는 없다. 모든 Fileserver 경로는 애플리케이션 정책을 보기 전에 servlet chain이 인증한다.
before any application policy is consulted, so such a setting could only ever have described a 그래서 그런 설정은 transport가 이미 거부한 권한을 설명할 수밖에 없다. 접근을 허락하는 것처럼 읽히지만
permission the transport had already refused — a configuration that reads as if it grants access 허락하지 않는 설정이 된다.
and does not.
The three tiers do not inherit. An admin role cannot delete through the data plane, and a write role 세 등급은 서로 물려받지 않는다. admin role은 data plane으로 삭제할 수 없고, write role은 management plane에
cannot reach the management plane — a role model where "can delete" implied "can force-delete" would 닿을 수 없다. 「삭제할 수 있으면 강제 삭제도 할 수 있다」는 role 모델이면 감사하지 않는 plane을 거쳐 감사하는
make the audited plane reachable through the unaudited one. plane에 닿게 된다.
`unenforced` authorizes everything and exists so a developer can exercise upload and download before `unenforced`는 모든 것을 허락한다. 개발자가 role 모델을 정하기 전에 업로드와 다운로드를 시험해 보라고 있는
deciding on a role model. It is refused under a production profile. 값이다. 운영 profile에서는 거부한다.
## Storage — `storage` ## 저장소 — `storage`
| Key | Default | Meaning | | Key | 기본값 | 뜻 |
| --- | --- | --- | | --- | --- | --- |
| `root` | `/var/lib/backend/files` | absolute path; the only place a path exists | | `root` | `/var/lib/backend/files` | 절대 경로. 경로가 존재하는 유일한 곳 |
| `publish-mode` | `atomic-move-preferred` | `atomic-move-required`, `atomic-move-preferred`, `metadata-pointer` | | `publish-mode` | `atomic-move-preferred` | `atomic-move-required`, `atomic-move-preferred`, `metadata-pointer` |
| `buffer-size` | `128KB` | bounds every transfer allocation; memory never scales with file size | | `buffer-size` | `128KB` | 모든 전송 할당의 상한. 메모리는 파일 크기에 따라 늘지 않는다 |
| `forbidden-root-ancestors` | `/app,/etc,/usr/share/nginx/html` | roots the storage root must not live under (webroot, config dirs) | | `forbidden-root-ancestors` | `/app,/etc,/usr/share/nginx/html` | 저장 루트가 그 아래 있으면 안 되는 root(webroot, 설정 폴더) |
`root` must be absolute. A relative root resolves against the process working directory, which is `root`는 절대 경로여야 한다. 상대 경로는 프로세스 작업 폴더를 기준으로 풀리고, 그 폴더는 container와
one path in a container and another in a test, so it is refused at binding time. 테스트에서 다르다. 그래서 바인딩할 때 거부한다.
Three former keys are gone, pinned as constants instead: staging and content share one FileStore, 예전 key 셋은 없어지고 상수로 고정됐다: staging과 content는 FileStore 하나를 같이 쓴다, symbolic link는
symbolic links are never followed, and the object and its directory are synced before READY. Each 절대 따라가지 않는다, 객체와 그 폴더는 READY 전에 sync한다. 셋 다 원자적 게시와 namespace 경계가 기대는
is an invariant the atomic publish and the namespace boundary are built on — a deployment that 불변식이다. 그중 하나를 끌 수 있는 배포는 같은 이름과 같은 테스트로 다른 capability를 돌리는 셈이다.
could switch one off would be running a different capability under the same name and the same
tests.
The storage provider has no selector either. There is exactly one implementation, and a `type` key 저장소 provider를 고르는 key도 없다. 구현이 정확히 하나이고, 허용 값이 하나뿐인 `type` key는 아무도
with one legal value is a promise of pluggability that nothing keeps. 지키지 않는 교체 가능성의 약속이다.
## Upload, download, transfer ## 업로드, 다운로드, 전송
| Key | Default | Meaning | | Key | 기본값 | 뜻 |
| --- | --- | --- | | --- | --- | --- |
| `upload.max-file-size` | `100MB` | hard ceiling; also drives `spring.servlet.multipart.max-file-size` | | `upload.max-file-size` | `100MB` | 넘을 수 없는 상한. `spring.servlet.multipart.max-file-size`도 이 값으로 정한다 |
| `upload.max-request-size` | `110MB` | request envelope; must be at least `max-file-size` | | `upload.max-request-size` | `110MB` | 요청 전체 크기. `max-file-size` 이상이어야 한다 |
| `upload.initial-reservation` | `8MB` | quota reserved when the length is unknown | | `upload.initial-reservation` | `8MB` | 길이를 모를 때 예약하는 할당량 |
| `upload.ttl` | `1h` | how long a resumable upload stays claimable | | `upload.ttl` | `1h` | 이어 올리기 업로드를 다시 잡을 수 있는 기간 |
| `upload.reservation-ttl` | `24h` | how long an unsettled quota reservation survives | | `upload.reservation-ttl` | `24h` | 정산하지 않은 할당량 예약이 남는 기간 |
| `upload.lease-duration` | `30s` | writer lease; renewed at one third of this | | `upload.lease-duration` | `30s` | writer lease. 이 값의 1/3마다 갱신한다 |
| `upload.max-parts` | `16` | multipart part ceiling | | `upload.max-parts` | `16` | multipart part 개수 상한 |
| `upload.require-content-length` | `false` | refuse chunked raw uploads | | `upload.require-content-length` | `false` | chunked raw 업로드를 거부한다 |
| `download.cache-control` | `private, no-store` | emitted on every content response | | `download.cache-control` | `private, no-store` | 모든 content 응답에 붙인다 |
| `download.inline-allowed` | `false` | scriptable content is always an attachment regardless | | `download.inline-allowed` | `false` | 스크립트가 될 수 있는 content는 이 값과 상관없이 늘 첨부 파일이다 |
| `download.max-ranges` | `1` | multi-range responses are opt-in | | `download.max-ranges` | `1` | 여러 범위 응답은 켜야 생긴다 |
| `download.max-range-bytes` | `100MB` | total bytes one ranged response may cover | | `download.max-range-bytes` | `100MB` | 범위 응답 하나가 덮을 수 있는 총 바이트 |
| `download.zero-copy-enabled` | `true` | hand large plaintext responses to the kernel | | `download.zero-copy-enabled` | `true` | 큰 평문 응답을 kernel에 넘긴다 |
| `download.zero-copy-minimum-bytes` | `16MB` | below this the syscall setup costs more than it saves | | `download.zero-copy-minimum-bytes` | `16MB` | 이보다 작으면 syscall 준비 비용이 아끼는 것보다 크다 |
| `transfer.core-size` / `max-size` / `queue-capacity` | `8` / `32` / `64` | blocking transfer pool bounds | | `transfer.core-size` / `max-size` / `queue-capacity` | `8` / `32` / `64` | blocking 전송 pool의 상한 |
| `transfer.await-seconds` | `300` | how long a transfer may occupy a pool thread | | `transfer.await-seconds` | `300` | 전송 하나가 pool 스레드를 잡을 수 있는 시간 |
Zero copy changes no header and no status. When storage declines it — an unreadable region, an zero copy는 헤더도 상태 코드도 바꾸지 않는다. 저장소가 거절하면(읽을 수 없는 영역, 지원하지 않는 backend)
unsupported backend — the response is streamed instead and is byte-identical. 응답을 스트리밍으로 보내고, 바이트는 똑같다.
## Verification — `verification` ## 검증 — `verification`
| Key | Default | Meaning | | Key | 기본값 | 뜻 |
| --- | --- | --- | | --- | --- | --- |
| `timeout` | `5s` | per-verifier ceiling | | `timeout` | `5s` | 검증기 하나의 상한 |
| `require-media-type-verdict` | `false` | refuse a file whose type could not be determined | | `require-media-type-verdict` | `false` | 형식을 정하지 못한 파일을 거부한다 |
| `inline-safe-profile` | `false` | accept scriptable content instead of quarantining it | | `inline-safe-profile` | `false` | 스크립트가 될 수 있는 content를 격리하지 않고 받는다 |
Set `inline-safe-profile: true` only when downloads are never served inline from a trusted origin. `inline-safe-profile: true`는 다운로드를 믿을 수 있는 origin에서 inline으로 절대 내보내지 않을 때만 쓴다.
## Quota and admission — `quota` ## 할당량과 허가 — `quota`
| Key | Default | Meaning | | Key | 기본값 | 뜻 |
| --- | --- | --- | | --- | --- | --- |
| `instance-upload-permits` | `16` | concurrent uploads this node admits | | `instance-upload-permits` | `16` | 이 노드가 받는 동시 업로드 수 |
| `scope-upload-permits` | `4` | concurrent uploads one caller (principal) admits; over it is a retryable `429` | | `scope-upload-permits` | `4` | 호출자(principal) 하나가 받는 동시 업로드 수. 넘으면 재시도할 수 있는 `429` |
| `direct-download-permits` | `64` | concurrent non-delegated downloads | | `direct-download-permits` | `64` | 위임하지 않은 동시 다운로드 수 |
| `soft-high-water` | `0.70` | storage fraction at which pressure is reported | | `soft-high-water` | `0.70` | 압박을 보고하기 시작하는 저장소 사용 비율 |
| `hard-high-water` | `0.85` | storage fraction at which uploads and copies are refused | | `hard-high-water` | `0.85` | 업로드와 copy를 거부하는 저장소 사용 비율 |
| `namespace-limit` | unset (unlimited) | most bytes one namespace may hold, live reservations plus committed usage; a create, copy or move that would pass it is refused with `QUOTA_EXCEEDED` (413) before any record, byte or namespace changes | | `namespace-limit` | 없음(제한 없음) | namespace 하나가 가질 수 있는 최대 바이트. 살아 있는 예약과 확정 사용량의 합이다. 이를 넘길 create, copy, move는 기록·바이트·namespace가 바뀌기 전에 `QUOTA_EXCEEDED`(413)로 거부한다 |
`namespace-limit` is checked against the usage the quota ledger reports and then reserved, in one `namespace-limit`은 할당량 ledger가 보고한 사용량과 비교한 뒤 예약한다. transaction 하나 안에서 하지만
transaction but without a per-namespace lock: reservations admitted at the same moment can overshoot namespace별 lock은 없다. 그래서 같은 순간에 허가된 예약들은 자기 크기만큼까지 한도를 넘을 수 있고, 그다음
the limit by at most their own size, and the next one is refused. A service that needs an exact cap 예약은 거부된다. 정확한 상한이 필요한 서비스는 자기 persistence 어댑터에 그 lock을 더한다.
adds that lock in its persistence adapter.
A move to another namespace carries the file's bytes in the ledger: in the transaction that relocates 다른 namespace로의 move는 ledger에서 파일의 바이트를 함께 옮긴다. 기록을 옮기는 transaction 안에서 대상의
the record it checks the target's limit, books the bytes as committed usage there and reclaims them 한도를 확인하고, 대상 쪽에 확정 사용량으로 올리고, 원래 쪽에서 회수한다. 거부된 move는 파일과 두
from the source. A refused move leaves the file, and both namespaces' usage, as they were. namespace의 사용량을 그대로 둔다.
When the storage fraction cannot be read, admission treats it as unknown and does not apply the 저장소 사용 비율을 읽지 못하면 허가 단계는 그것을 모름으로 보고 high-water 규칙을 적용하지 않는다. 지어낸
high-water rule — a synthetic `0` would silently disable the guard, and a synthetic `1` would take `0`은 보호 장치를 조용히 끄고, 지어낸 `1`은 syscall 하나 실패로 capability를 내린다.
the capability down over a failed syscall.
## Background reclamation — `cleanup` ## 백그라운드 회수 — `cleanup`
| Key | Default | Meaning | | Key | 기본값 | 뜻 |
| --- | --- | --- | | --- | --- | --- |
| `enabled` | `true` | run the cleanup worker on this node; `false` logs a startup warning | | `enabled` | `true` | 이 노드에서 cleanup worker를 돌린다. `false`면 시작할 때 경고를 남긴다 |
| `interval` | `60s` | fixed delay between batches, not fixed rate | | `interval` | `60s` | batch 사이의 고정 지연. 고정 주기가 아니다 |
| `max-items` | `100` | items one batch may claim | | `max-items` | `100` | batch 하나가 가져갈 수 있는 항목 수 |
| `max-bytes` | `1GB` | bytes one batch may reclaim | | `max-bytes` | `1GB` | batch 하나가 회수할 수 있는 바이트 |
| `retry-backoff` | `5m` | how long a failed item waits before it is due again | | `retry-backoff` | `5m` | 실패한 항목이 다시 차례가 될 때까지 기다리는 시간 |
The worker is on by default: it deletes only what the cleanup queue names, and without it cancelled worker는 기본으로 켜져 있다. cleanup 큐가 이름 댄 것만 지운다. worker가 없으면 취소·만료된 staging, 거부·
and expired staging, rejected and deleted content stay on the volume until the hard high-water mark 삭제된 content가 hard high-water가 모든 업로드를 막을 때까지 volume에 남는다. 노드 하나가 worker를 끌 수
stops every upload. A node may turn it off — for instance when another node runs it — and startup 있다(예: 다른 노드가 돌릴 때). 그러면 시작할 때 `app.fileserver-platform.cleanup.enabled=false`를 이름 댄
then logs a `WARN` naming `app.fileserver-platform.cleanup.enabled=false`. A node without it still `WARN`을 남긴다. worker가 없는 노드도 cleanup 항목을 큐에 넣는다. 다른 노드나 운영자가 회수한다. (경고 대신
queues cleanup items; another node or an operator reclaims them. (A required "reason" key was 필수 「이유」 key를 두는 안도 검토했지만 버렸다. 시작 경고를 끄는 것 말고는 효과가 없는 설정을 worker 아닌
considered instead of the warning and rejected: it would be a setting whose only effect is to 모든 노드가 들고 다니게 된다.) 여덟 번 실패한 항목은 영원히 재시도하지 않고 내려놓는다. 버리지 않고 세워
silence startup, carried by every non-worker node.) An item that fails 두므로 운영자에게는 계속 보인다.
eight times is abandoned rather than retried forever — it stays visible to an operator, parked
rather than discarded.
Each pass also expires uploads whose `expiresAt` has passed (the record becomes `EXPIRED` and its 매 회차는 이런 일도 한다.
staged bytes are queued), purges orphans the admin plane retired to quarantine, and runs
reconciliation over stale `UPLOADED`/`VERIFYING`/`FAILED` records, so an ambiguous publish settles
without an operator.
## Copy and move targets - `expiresAt`이 지난 업로드를 만료시킨다(기록은 `EXPIRED`가 되고 staging 바이트는 큐에 들어간다).
- admin plane이 격리로 내린 고아 객체를 지운다.
- 오래된 `UPLOADED`/`VERIFYING`/`FAILED` 기록에 대해 맞춰 보기를 돌린다. 그래서 결과를 모르는 게시가 운영자
없이 정리된다.
`app.fileserver-platform.target-namespaces` (`APP_FILESERVER_PLATFORM_TARGET_NAMESPACES`, a comma ## Copy와 move 대상
list, empty by default) names the namespaces copy and move may write into besides
`default-namespace`, which is always allowed. The target namespace of a copy or a move comes from the request body, and a namespace is also the `app.fileserver-platform.target-namespaces`(`APP_FILESERVER_PLATFORM_TARGET_NAMESPACES`, 쉼표 목록, 기본은
quota grouping. Any other target is refused with `ACCESS_DENIED` before a byte moves or a 비어 있음)는 늘 허용되는 `default-namespace` 말고 copy와 move가 쓸 수 있는 namespace를 적는다. copy나 move의
reservation is taken. 대상 namespace는 요청 본문에서 오고, namespace는 할당량을 묶는 단위이기도 하다. 그 밖의 대상은 바이트가
움직이거나 예약을 잡기 전에 `ACCESS_DENIED`로 거부한다.
## Management plane — `admin` ## Management plane — `admin`
| Key | Default | Meaning | | Key | 기본값 | 뜻 |
| --- | --- | --- | | --- | --- | --- |
| `enabled` | `false` | expose `/internal/fileserver/**` | | `enabled` | `false` | `/internal/fileserver/**`를 연다 |
| `orphan-minimum-age` | `1h` | how long an unreferenced object must exist before a scan may name it | | `orphan-minimum-age` | `1h` | 참조 없는 객체가 scan에 이름이 오르기 전에 존재해야 하는 시간 |
Publishing content and committing its record are two steps. Anything younger than content를 게시하는 것과 그 기록을 확정하는 것은 두 단계다. `orphan-minimum-age`보다 어린 것은 버려진 것이
`orphan-minimum-age` is assumed to be mid-commit rather than abandoned; shortening this makes 아니라 확정 중인 것으로 본다. 이 값을 줄이면 동시 업로드가 고아처럼 보인다.
concurrent uploads look like orphans.
## Front-proxy delegation — `nginx` ## 프런트 프록시 위임 — `nginx`
| Key | Default | Meaning | | Key | 기본값 | 뜻 |
| --- | --- | --- | | --- | --- | --- |
| `enabled` | `false` | emit `X-Accel-Redirect` instead of a body | | `enabled` | `false` | 본문 대신 `X-Accel-Redirect`를 내보낸다 |
| `internal-prefix` | `/__files/` | must be an `internal` location resolving to the content root | | `internal-prefix` | `/__files/` | content root로 풀리는 `internal` location이어야 한다 |
| `object-suffix` | `.bin` | layout suffix the proxy appends | | `object-suffix` | `.bin` | 프록시가 붙이는 배치 접미사 |
| `minimum-size` | `16MB` | below this the application serves the transfer itself | | `minimum-size` | `16MB` | 이보다 작으면 애플리케이션이 직접 전송한다 |
Delegation is decided only after authorization and the READY gate, so an internal redirect can only 위임은 권한 확인과 READY 관문을 지난 뒤에만 정한다. 그래서 내부 redirect는 호출자가 이미 읽어도 되는
ever name content the caller was already allowed to read. content만 가리킬 수 있다.
## Protocols — `tus` ## 프로토콜 — `tus`
| Key | Default | Meaning | | Key | 기본값 | 뜻 |
| --- | --- | --- | | --- | --- | --- |
| `enabled` | `false` | expose the tus 1.0 endpoints | | `enabled` | `false` | tus 1.0 endpoint를 연다 |
The HTTPbis resumable-upload draft-12 surface is experimental and documented in HTTPbis resumable-upload draft-12 면은 실험 단계이고 [support-matrix.md](support-matrix.md)에 적었다.
[support-matrix.md](support-matrix.md).
+133 -148
View File
@@ -1,216 +1,201 @@
# Fileserver — deviations from the design # Fileserver — 설계와 다른 곳
The design specification and the implementation plan are frozen documents. Where implementation 설계 명세와 구현 계획서는 고정된 문서다. 구현하다 보니 명세가 덜 정해졌거나 스스로 모순인 곳이 있었다.
found them under-specified or self-contradicting, the resolution is recorded here rather than by 그 해결은 명세를 고치지 않고 여기 적는다. 항목마다 그 결정을 고정하는 테스트를 적는다.
editing the specification, and every entry names the test that pins the decision.
## Resolved inconsistencies in the state machine and contracts ## 상태 기계와 계약에서 해결한 모순
### 1. `CREATED → FAILED` has no edge in the transition table ### 1. 전이 표에 `CREATED → FAILED` edge가 없다
A create that fails after the record exists must end in `FAILED`, but the table has no direct edge. 기록이 생긴 뒤 실패한 create는 `FAILED`로 끝나야 하는데, 표에 바로 가는 edge가 없다. 그래서 기록은
The record therefore walks `CREATED → UPLOADING → FAILED`, which is also the honest reading: the `CREATED → UPLOADING → FAILED`로 간다. 이것이 정직한 읽기이기도 하다. 업로드는 실패하기 전에 이미 허가됐다.
upload had been admitted before it failed.
Pinned by `ResumableUploadUseCasesTest` (application-fileserver). 고정하는 테스트: `ResumableUploadUseCasesTest`(application-fileserver).
### 2. `ContentKey`'s alphabet admits a leading separator ### 2. `ContentKey`의 글자 집합이 맨 앞 구분자를 허락한다
The design's key pattern `[a-z0-9/_-]{16,200}` matches `/etc/passwd/...`. Rejecting an absolute path 설계의 key 패턴 `[a-z0-9/_-]{16,200}`은 `/etc/passwd/...`에 맞는다. 값 타입에서 절대 경로를 거부하면 설계가
at the value type would change a design-fixed contract, so the stricter shape check lives in 고정한 계약이 바뀐다. 그래서 더 엄격한 모양 검사는 §12.2 규칙 1에 따라 `PhysicalPathResolver`에 둔다.
`PhysicalPathResolver`, per §12.2 rule 1 — the only place that turns an identifier into a path. 식별자를 경로로 바꾸는 유일한 곳이다.
Pinned by `PhysicalPathResolverTest`. 고정하는 테스트: `PhysicalPathResolverTest`.
### 3. `VERIFYING → DELETING` has no edge ### 3. `VERIFYING → DELETING` edge가 없다
Deleting a file that is mid-verification has no legal transition. The lifecycle service refuses it 검증 중인 파일을 지우는 합법적 전이가 없다. lifecycle 서비스는 edge를 지어내지 않고 `409 FILE_NOT_READY`로
with `409 FILE_NOT_READY` rather than inventing an edge, which matches the allowed-state list the 거부한다. JPA `markDeleting` 문이 이미 강제하던 허용 상태 목록과 같다.
JPA `markDeleting` statement already enforced.
Pinned by `FileLifecycleUseCasesTest`. 고정하는 테스트: `FileLifecycleUseCasesTest`.
### 4. `If-Match` is specified as an ETag but the lifecycle was designed around the row version ### 4. `If-Match`는 ETag로 정해졌는데 lifecycle은 행 version을 기준으로 설계됐다
The HTTP contract sends an entity tag; the metadata store guards on a numeric version. The service HTTP 계약은 entity tag를 보내고, metadata 저장소는 숫자 version으로 막는다. 서비스는
takes `Optional<String> expectedEtag` and compares against the record's strong validator, so the `Optional<String> expectedEtag`를 받아 기록의 strong validator와 비교한다. 그래서 client가 보낸 선행 조건이
precondition a client sends is the precondition that is checked. 곧 검사하는 선행 조건이다.
Pinned by `FileLifecycleUseCasesTest`. 고정하는 테스트: `FileLifecycleUseCasesTest`.
### 5. The filename policy left `:` intact ### 5. 파일 이름 정책이 `:`를 남겼다
`C:\Windows\system.ini` sanitized to `C:Windowssystem.ini` — a drive-qualified name surviving into `C:\Windows\system.ini`가 `C:Windowssystem.ini`로 정리됐다. 드라이브가 붙은 이름이 표시 문자열과 헤더까지
display text and headers. `:` joined the structural strip set. 살아남았다. `:`를 구조 문자 제거 집합에 넣었다.
Pinned by `FileserverHardeningContractTest` and `AmbiguousFilesystemOperationDetectorTest`. 고정하는 테스트: `FileserverHardeningContractTest`, `AmbiguousFilesystemOperationDetectorTest`.
## Additions the design implies but does not specify ## 설계가 암시하지만 정하지 않은 추가
### 6. `fs_recovery_item` ### 6. `fs_recovery_item`
§10.2 lists five core tables and none of them can hold the recovery queue, yet §29.3 requires one: §10.2는 핵심 테이블 다섯을 나열하는데 그중 어느 것도 복구 큐를 담을 수 없다. 그런데 §29.3은 복구 큐를
reconciliation reports files whose bytes and metadata disagree, and holding that list in memory 요구한다. 맞춰 보기는 바이트와 metadata가 어긋나는 파일을 보고하는데, 그 목록을 메모리에 두면 재시작이 끊은
would lose exactly the cases a restart interrupted. Added in 바로 그 경우를 잃는다. `V2__fileserver_recovery_and_staging_cleanup.sql`에서 더했다. 파일마다 열린 항목은
`V2__fileserver_recovery_and_staging_cleanup.sql` with one open item per file, so repeated sweeps 하나다. 그래서 같은 정리를 반복해도 로그가 쌓이지 않고 작업 목록이 갱신된다.
update a worklist rather than accumulating a log.
Pinned by `PostgreSqlFileserverReclamationIntegrationTest`. 고정하는 테스트: `PostgreSqlFileserverReclamationIntegrationTest`.
### 7. `fs_cleanup_item.upload_id` ### 7. `fs_cleanup_item.upload_id`
A staging object is addressed by upload, not by file. Without this column a queued staging cleanup staging 객체는 파일이 아니라 업로드로 가리킨다. 이 열이 없으면 큐에 넣은 staging 정리가 이미 게시된
could name only already-published content, so a cancelled or expired upload left bytes nothing could content만 가리킬 수 있어서, 취소·만료된 업로드는 아무도 찾지 못하는 바이트를 남겼다. 같은 마이그레이션에서
find. Added in the same migration, with a check constraint that an item names exactly one target. 더했고, 항목이 대상 정확히 하나를 가리키는지 check 제약을 둔다.
Pinned by `PostgreSqlFileserverReclamationIntegrationTest`. 고정하는 테스트: `PostgreSqlFileserverReclamationIntegrationTest`.
### 8. `ContentReferenceLedgerPort` and `StagingUploadLocatorPort` ### 8. `ContentReferenceLedgerPort`와 `StagingUploadLocatorPort`
The orphan scan must ask whether a record still claims a physical object, and reconciliation must 고아 scan은 어떤 기록이 아직 물리 객체를 가리키는지 물어야 하고, 맞춰 보기는 파일을 마지막으로 staging한
map a file back to the upload that last staged it. Neither question is answerable through the 업로드로 되짚어야 한다. 설계에 적힌 그대로의 `FileMetadataPort`나 `UploadSessionPort`로는 어느 질문에도
design's `FileMetadataPort` or `UploadSessionPort` as written. Rather than widen those 답할 수 없다. 설계가 고정한 interface를 넓히지 않고, 둘 다 메서드 하나짜리 좁은 port로 만들었다.
design-fixed interfaces, both are narrow single-method ports.
Pinned by `PostgreSqlFileserverReclamationIntegrationTest` and `LocalOrphanScanAdapterTest`. 고정하는 테스트: `PostgreSqlFileserverReclamationIntegrationTest`, `LocalOrphanScanTest`.
## Interpretations ## 해석
### 9. Quota settlement is FIFO within a scope ### 9. 할당량 정산은 범위 안에서 FIFO다
Nothing links a reservation row to the upload that took it, and the design deliberately reclaims 예약 행과 그것을 잡은 업로드를 잇는 것이 없다. 그리고 설계는 upload session에 예약 id를 끼워 넣지 않고
stragglers by TTL and the `STALE_QUOTA_RESERVATION` cleanup type rather than threading a reservation TTL과 `STALE_QUOTA_RESERVATION` cleanup 유형으로 남은 것을 회수한다. 그래서 `QuotaCommitPort`는 그 파일의
id through the upload session. `QuotaCommitPort` therefore settles the oldest live reservation in namespace에서 가장 오래된 살아 있는 예약을 정산한다.
the file's namespace.
Which row closes does not change any quota decision: enforcement sums reserved and committed bytes 어느 행이 닫히는지는 할당량 판단을 바꾸지 않는다. 강제는 범위별로 예약·확정 바이트를 합하고 행 하나하나는
per scope and never reads an individual row. Concurrent uploads of different sizes can leave the 읽지 않는다. 크기가 다른 동시 업로드는 예약 합계를 잠깐 높거나 낮게 남길 수 있고, 각각 정산되면서 맞춰진다.
reserved total transiently high or low, and it converges as each settles. Durable usage with no live 뒤에 살아 있는 예약이 없는 확정 사용량(TTL보다 오래 걸린 업로드)도 기록한다. 조용히 덜 세는 ledger는 잠깐
reservation behind it — an upload that outlived its TTL — is still recorded, because a ledger that 부정확한 ledger보다 나쁘다.
silently under-counts is worse than one that is briefly imprecise.
Pinned by `PostgreSqlFileserverReclamationIntegrationTest`. 고정하는 테스트: `PostgreSqlFileserverReclamationIntegrationTest`.
### 10. Zero copy is a channel transfer, not a file handoff ### 10. Zero copy는 파일 넘기기가 아니라 channel 전송이다
Task 22 asks for zero copy on local files; §19 forbids a `Path` leaving the storage adapter, and §5 계획서 Task 22는 로컬 파일에 zero copy를 요구한다. 그런데 §19는 `Path`가 저장소 어댑터를 떠나는 것을 금하고,
of the plan forbids adding `Path` to the content store. WebFlux's zero-copy API takes a `Path`, so 계획서 §5는 content store에 `Path`를 더하는 것을 금한다. WebFlux의 zero-copy API는 `Path`를 받으므로 그 길은
that route is closed. 닫혀 있다.
The servlet path takes the other one: `ZeroCopyDownloadPort` receives a `WritableByteChannel` from servlet 경로는 다른 길을 쓴다. `ZeroCopyDownloadPort`는 transport에서 `WritableByteChannel`을 받고, 저장소
the transport and the storage adapter performs `FileChannel.transferTo` into it. That is a genuine 어댑터가 그 안으로 `FileChannel.transferTo`를 한다. 파일 시스템 개념이 저장소를 떠나지 않는 진짜 kernel 수준
kernel-level transfer with no filesystem concept leaving storage. The reactive path continues to 전송이다. reactive transport는 2026-09-25에 지웠다([support-matrix.md](support-matrix.md)).
stream with bounded demand.
Zero copy is an optimization with no observable difference: when storage declines, the response is zero copy는 관측 가능한 차이가 없는 최적화다. 저장소가 거절하면 응답은 스트리밍되고 바이트는 똑같다.
streamed and is byte-identical.
Pinned by `LocalStorageGatewayContractTest` and `ZeroCopyEligibilityTest`. 고정하는 테스트: `LocalStorageGatewayContractTest`, `ZeroCopyEligibilityTest`.
### 11. The Fileserver JPA stores are gated on the capability switch ### 11. Fileserver JPA 저장소는 capability 스위치 뒤에 있다
The metadata store, session store, quota service, queues, ledger, and staging locator carry metadata 저장소, session 저장소, 할당량 서비스, 큐, ledger, staging locator는 `adapter:outbound:persistence-fileserver`
`@ConditionalOnProperty(app.fileserver-platform.enabled)` even though the rest of leaf에 있다. 그 leaf의 auto-configuration root `FileserverJpaPersistenceConfig`가
`adapter:outbound:persistence-jpa` is unconditional. `@ConditionalOnProperty(app.fileserver-platform.enabled)` 하나로 entity 스캔, Spring Data repository, 저장소
bean을 모두 가린다.
게이트가 없으면 persistence 모듈을 포함한 조립 루트는 Fileserver를 쓰지 않아도 이 bean들을 만들고, 그 bean마다 이 관문이 없으면 persistence 모듈을 포함한 조립 루트는 Fileserver를 쓰지 않아도 이 bean들을 만들고, 그
Fileserver 설정만 주는 협력 객체가 필요하다. That is the same rule the design states for the transport bean마다 Fileserver 설정만 주는 협력 객체가 필요하다. 설계가 transport 면에 대해 말한 규칙을 persistence에
surface, applied to persistence: no surface appears merely because the dependency is present. 적용한 것이다: 의존성이 있다는 이유만으로 면이 나타나지 않는다.
`FileStateMachine` is bound alongside them, in `FileserverStorageConfiguration`. It had no 예전의 `FileStateMachine` bean은 지웠다. 상태 전이 검사는 `FileState.canTransitionTo`가 한다
production binding at all before, which made the metadata store unconstructible in any (`docs/capability-status.md` 「제거된 코드」).
component-scanned context.
Pinned by `SampleApplicationContextTest` (the capability off) and 고정하는 테스트: `FileserverPersistenceActivationTest`(스캔이 스위치 뒤에 있음),
`FileserverRuntimeAssemblyTest` (the capability on). `FileserverRuntimeAssemblyTest`(capability를 켬), `FileStateTransitionTest`(전이 표).
### 12. Transaction boundaries are owned by the application services, and are deliberately narrow ### 12. Transaction 경계는 애플리케이션 서비스가 갖고, 일부러 좁다
The design does not say where a transaction begins. The repository does: 설계는 transaction이 어디서 시작하는지 말하지 않는다. 저장소가 말한다. `adapter:outbound:persistence-jpa`는
`adapter:outbound:persistence-jpa` forbids a repository adapter from owning a `@Transactional` repository 어댑터가 `@Transactional` 경계를 갖는 것을 금하고, `application-core`가 `TransactionPort`로 경계를
boundary, and `application-core` owns them through `TransactionPort`. The Fileserver follows that 가진다. Fileserver도 이 규칙을 따른다. 여기 있는 `Jpa*` 저장소는 자기 `@Transactional`을 선언하지 않는다.
rule — every `Jpa*` store here declares no `@Transactional` of its own.
What is specific to this capability is how narrow the boundaries are. A boundary covers a contiguous 이 capability에 특별한 것은 경계가 얼마나 좁은가다. 경계 하나는 이어진 metadata 쓰기를 덮고 **저장소 호출
run of metadata writes and **stops before every storage call**, because a filesystem operation 앞에서 늘 멈춘다**. DB transaction 안의 파일 시스템 작업은 바이트 전송 시간 내내 connection을 잡기 때문이다.
inside a database transaction would hold a connection for the length of a byte transfer. The upload 그래서 업로드 경로의 경계는 하나가 아니라 셋이다: lease 잡기, 바이트 전송, offset 확정.
path therefore has three boundaries, not one: acquire the lease, transfer the bytes, commit the
offset.
Where several stores must agree, they share one boundary: 여러 저장소가 함께 맞아야 하는 곳은 경계 하나를 같이 쓴다.
| Unit | Why it is one boundary | | 단위 | 경계 하나인 이유 |
| --- | --- | | --- | --- |
| reserve quota + insert record + create session | a reservation that outlived a failed insert holds capacity for a file that never existed | | 할당량 예약 + 기록 insert + session 생성 | insert가 실패한 뒤 남은 예약은 존재한 적 없는 파일의 용량을 잡는다 |
| READY transition + quota commit | a finished file whose reservation was never converted holds capacity until the reservation expires | | READY 전이 + 할당량 확정 | 예약이 확정으로 바뀌지 않은 완료 파일은 예약이 만료될 때까지 용량을 잡는다 |
| `markDeleting` + enqueue cleanup | a file that stopped being reachable with nothing queued to reclaim it is never collected | | `markDeleting` + cleanup 큐 넣기 | 닿을 수 없게 됐는데 회수할 항목이 큐에 없는 파일은 영영 수거되지 않는다 |
| content delete settlement: reclaim + retire record + close queue item | half of it leaves the item to be retried against content that no longer exists | | content 삭제 정산: 회수 + 기록 내리기 + 큐 항목 닫기 | 절반만 되면 이미 없는 content를 대상으로 항목이 재시도된다 |
What this cannot make atomic is the storage/metadata seam itself — no database boundary could. That 이렇게 해도 저장소/metadata 이음매 자체는 원자적으로 만들 수 없다. 어떤 DB 경계도 못 한다. 그 이음매 때문에
seam is exactly what the ambiguous-completion path and the reconciler exist for, and the one 결과를 모르는 완료 경로와 맞춰 보기가 있다. 남은 손으로 쓴 보상 하나(기록이 확정된 뒤 staging 생성이 실패한
hand-written compensation that remains (staging creation failing after the records committed) is 경우)도 같은 이유로 있다.
there for the same reason.
Pinned by `FileserverRoundTripContractTest` against real PostgreSQL; the application tests use 고정하는 테스트: 애플리케이션 테스트는 경계를 그 자리에서 돌리며 세는 `DirectTransactions`를 쓴다. 실제
`DirectTransactions`, which runs a boundary inline and counts it. PostgreSQL에서 조립 전체는 `FileserverCompositionIntegrationTest`(app-bootstrap `integrationTest`)가 돈다.
예전에 이 경계를 실제 PostgreSQL에서 고정하던 `FileserverRoundTripContractTest`는 지금 없다.
## Not implemented ## 구현하지 않은 것
### `AsyncContentStore`, `CapacityAwareContentStore`, `CopyCapableContentStore`, `DelegatedDownloadStore` ### `AsyncContentStore`, `CapacityAwareContentStore`, `CopyCapableContentStore`, `DelegatedDownloadStore`
Four optional content-store SPIs are declared in `application-core` with no implementation. Each is `application-fileserver`에 구현 없이 선언돼 있던 선택 content-store SPI 넷이다. 구현도 호출도 없어서 지웠다
an extension point for a backend this template does not ship: (`docs/capability-status.md` 「제거된 코드」). 각각 이 템플릿이 내놓지 않는 backend를 위한 확장 지점이었다.
- `AsyncContentStore` — for a backend whose native client is non-blocking. The local platform is - `AsyncContentStore` — native client가 non-blocking인 backend용. 로컬 플랫폼은 blocking이다.
blocking, and the reactive transport bridges to it on a dedicated I/O scheduler. - `CapacityAwareContentStore` — 용량은 로컬 플랫폼이 구현하는 `StorageHealthPort`와 `StorageUsagePort`로
- `CapacityAwareContentStore` — capacity is reported through `StorageHealthPort` and 보고한다.
`StorageUsagePort`, which the local platform implements. - `CopyCapableContentStore` — 서버 쪽 copy는 `CopyContentPort`가 한다. 로컬 플랫폼에는 스트리밍 copy보다 싼
- `CopyCapableContentStore` — server-side copy is delivered by `CopyContentPort`; the local 방법이 없다.
platform has no cheaper primitive than a streamed copy. - `DelegatedDownloadStore` — 위임은 transport 경계에서 nginx `X-Accel-Redirect` 전략이 한다. 저장소가 끼어들
- `DelegatedDownloadStore` — delegation is delivered at the transport boundary by the nginx 필요가 없다.
`X-Accel-Redirect` strategy, which needs no store participation.
`ContentStoreCapabilities` reports what the running store actually supports, so no unimplemented SPI `ContentStoreCapabilities`가 실행 중인 저장소가 실제로 지원하는 것을 보고한다. 그래서 구현하지 않은 것을 쓸 수
is advertised as available. 있다고 광고하지 않는다.
## The repository's application-layer contract ## 저장소의 애플리케이션 계층 계약
### 5. Fileserver operations are use cases (resolved, owner decision 32) ### 5. Fileserver 연산은 use case다 (해결됨, 소유자 결정 32)
Every operation the transport reaches is a `CommandUseCase` or `QueryUseCase` behind a one-method transport가 닿는 모든 연산은 `application.fileserver.port.in`의 메서드 하나짜리 port 뒤에 있는
port in `application.fileserver.port.in` — create, append, status, cancel, finalize and the `CommandUseCase`나 `QueryUseCase`다.
single-request upload; describe, prepare, open and transfer for downloads; delete, copy and move;
and the eight management-plane operations. Each implementation (`*ApplicationUseCase`) declares its
`@UseCaseCapability`, so the ArchUnit rules that check transaction mode, repository access and
outbound calls now see the Fileserver like every other feature.
Two authorities guard a write, and both stay: - 업로드: create, append, status, cancel, finalize, 요청 하나짜리 업로드
- 다운로드: describe, prepare, open, transfer
- delete, copy, move
- management plane 연산 여덟
| Check | Where | Decides | 구현(`*ApplicationUseCase`)마다 `@UseCaseCapability`를 선언한다. 그래서 transaction 방식, repository 접근,
외부 호출을 검사하는 ArchUnit 규칙이 이제 Fileserver를 다른 기능과 똑같이 본다.
쓰기를 막는 권한은 둘이고, 둘 다 남는다.
| 검사 | 위치 | 정하는 것 |
| --- | --- | --- | | --- | --- | --- |
| `@RequiresPermission("file:…")` | the use case's proxy, enforced by the web adapter's method security | whether the caller's roles grant the operation at all | | `@RequiresPermission("file:…")` | use case의 proxy. web 어댑터의 method security가 강제한다 | 호출자의 role이 그 연산을 아예 허락하는지 |
| `FileAccessPolicyPort` | inside the use case, before any side effect | the tier (read/write/admin), and that the caller owns the file in its tenant | | `FileAccessPolicyPort` | use case 안, 부수 효과 전 | 등급(read/write/admin), 그리고 호출자가 자기 tenant에서 그 파일의 소유자인지 |
The permissions are `file:read` (describe, download, upload status), `file:upload` (create, 권한은 `file:read`(describe, 다운로드, 업로드 상태), `file:upload`(create, append, finalize, cancel, 요청
append, finalize, cancel, the single-request upload), `file:delete`, `file:copy`, `file:move` and 하나짜리 업로드), `file:delete`, `file:copy`, `file:move`, `file:admin`(모든 management plane 연산)이다.
`file:admin` (every management-plane operation). `security.yml` grants them to `ROLE_FILE_READ`, `security.yml`은 이 권한을 fileserver 자신의 기본 등급 role인 `ROLE_FILE_READ`, `ROLE_FILE_WRITE`,
`ROLE_FILE_WRITE` and `ROLE_FILE_ADMIN` — the fileserver's own default tier roles — so a caller `ROLE_FILE_ADMIN`에 준다. 그래서 등급을 가진 호출자는 그 권한도 가진다. 등급 role 이름을 바꾸거나 다른 role
holding a tier holds its permissions. A deployment that renames the tier roles, or supplies its own 이름으로 자기 `FileAccessPolicyPort`를 주는 배포는 `app.authz.role-permissions`에도 그 이름을 대응시킨다.
`FileAccessPolicyPort` under other role names, maps those names in `security.access-policy: unenforced`는 등급과 소유 검사만 풀고 권한 관문은 절대 풀지 않는다.
`app.authz.role-permissions` too; `security.access-policy: unenforced` relaxes only the
tier and ownership check, never the permission gate.
The resumable transfers run on the transfer pool, and method security reads the security context 이어 올리기 전송은 전송 pool에서 돌고, method security는 호출한 스레드의 security context를 읽는다. 그래서
of the calling thread, so `BlockingTransferExecutor` carries the request's context onto the worker `BlockingTransferExecutor`가 요청의 context를 worker로 옮긴다(`BlockingTransferExecutorSecurityContextTest`).
(`BlockingTransferExecutorSecurityContextTest`). Without it an authenticated append was refused as 이것이 없으면 인증한 append가 익명으로 거부됐다.
anonymous.
What is not a use case is what no transport calls: `CleanupService` and use case가 아닌 것은 어떤 transport도 부르지 않는 것이다. `CleanupService`와 `FileReconciliationService`는
`FileReconciliationService` are driven by background workers with no caller identity, and a 호출자 신원이 없는 백그라운드 worker가 돌린다. 상태를 바꾸는 use case는 scheduler가 가질 수 없는 권한을
mutating use case must declare a permission a scheduler could not hold. 선언해야 한다. `FileserverUseCaseContractDeviationTest`가 그 목록을 고정한다.
`FileserverUseCaseContractDeviationTest` freezes that list.
The HTTP status vocabulary on `FileserverErrorCode` stays in the application layer, for the reason
this section used to give: the servlet transport and the Nginx delegation path must not answer the
same failure with different statuses.
`FileserverErrorCode`의 HTTP 상태 어휘는 애플리케이션 계층에 남는다. 이 절이 예전에 든 이유 그대로다:
servlet transport와 Nginx 위임 경로가 같은 실패에 다른 상태로 답하면 안 된다.
+77 -82
View File
@@ -1,35 +1,34 @@
# Fileserver HTTP contract # Fileserver HTTP 계약
Every public endpoint is listed here. `FileserverDocumentationCoverageTest` scans the controllers 모든 공개 endpoint를 여기 적는다. `FileserverDocumentationCoverageTest`가 controller를 훑어서 빠진 것이 있으면
and fails if one is missing, so this file cannot silently fall behind the code. 실패하므로, 이 파일은 코드보다 조용히 뒤처질 수 없다.
## Public endpoints ## 공개 endpoint
| Method | Path | Success | Notes | | Method | Path | 성공 | 비고 |
|---|---|---|---| |---|---|---|---|
| POST | `/v1/files` | `201` READY, `202` VERIFYING | multipart single upload | | POST | `/v1/files` | `201` READY, `202` VERIFYING | multipart 단일 업로드 |
| POST | `/v1/files:raw` | `201`, `202` | the whole request body is the file | | POST | `/v1/files:raw` | `201`, `202` | 요청 본문 전체가 파일이다 |
| POST | `/v1/files:batch` | `200` | ordered per-part results; explicitly non-atomic | | POST | `/v1/files:batch` | `200` | part별 결과를 순서대로 준다. 명시적으로 원자적이지 않다 |
| GET | `/v1/files/{fileId}` | `200` | public metadata; never a content key or path | | GET | `/v1/files/{fileId}` | `200` | 공개 metadata. content key나 경로는 절대 주지 않는다 |
| GET | `/v1/files/{fileId}/content` | `200`, `206`, `304` | download | | GET | `/v1/files/{fileId}/content` | `200`, `206`, `304` | 다운로드 |
| HEAD | `/v1/files/{fileId}/content` | `200`, `304` | identical headers, no body | | HEAD | `/v1/files/{fileId}/content` | `200`, `304` | 같은 헤더, 본문 없음 |
| DELETE | `/v1/files/{fileId}` | `202`, `204` | logical delete first | | DELETE | `/v1/files/{fileId}` | `202`, `204` | 먼저 논리 삭제 |
| POST | `/v1/files/{fileId}:copy` | `202` | create-only target | | POST | `/v1/files/{fileId}:copy` | `202` | 대상은 새로 만들기만 한다 |
| POST | `/v1/files/{fileId}:move` | `200` | namespace change only, bytes stay; the file's quota moves with it, and a target namespace past its `namespace-limit` is `413` | | POST | `/v1/files/{fileId}:move` | `200` | namespace만 바뀌고 바이트는 그대로다. 파일의 할당량도 함께 옮긴다. 대상 namespace가 `namespace-limit`을 넘으면 `413` |
| OPTIONS | `/v1/uploads` | `204` | tus capability discovery | | OPTIONS | `/v1/uploads` | `204` | tus capability 조회 |
| POST | `/v1/uploads` | `201` | tus creation | | POST | `/v1/uploads` | `201` | tus 생성 |
| HEAD | `/v1/uploads/{uploadId}` | `204` | tus offset | | HEAD | `/v1/uploads/{uploadId}` | `204` | tus offset |
| PATCH | `/v1/uploads/{uploadId}` | `204` | tus append | | PATCH | `/v1/uploads/{uploadId}` | `204` | tus 이어 쓰기 |
| DELETE | `/v1/uploads/{uploadId}` | `204` | tus termination | | DELETE | `/v1/uploads/{uploadId}` | `204` | tus 종료 |
| POST | `/v1/experimental/draft12/uploads` | `201` | Experimental; off by default | | POST | `/v1/experimental/draft12/uploads` | `201` | Experimental. 기본으로 꺼져 있다 |
| PATCH | `/v1/experimental/draft12/uploads/{uploadId}` | `204` | Experimental; off by default | | PATCH | `/v1/experimental/draft12/uploads/{uploadId}` | `204` | Experimental. 기본으로 꺼져 있다 |
## Management endpoints ## 관리 endpoint
Reachable only where both `app.fileserver-platform.enabled=true` and `app.fileserver-platform.enabled=true`와 `app.fileserver-platform.admin.enabled=true`가 둘 다 있을 때만 닿는다.
`app.fileserver-platform.admin.enabled=true`, gated at the servlet chain on servlet chain에서 `app.fileserver-platform.security.admin-roles`로 막고, 공개 port가 아니라 관리 port에 두라고
`app.fileserver-platform.security.admin-roles`, and intended for a management 만든 것이다.
port rather than the public one.
| Method | Path | | Method | Path |
|---|---| |---|---|
@@ -42,38 +41,37 @@ port rather than the public one.
| GET | `/internal/fileserver/uploads/incomplete` | | GET | `/internal/fileserver/uploads/incomplete` |
| POST | `/internal/fileserver/uploads:cleanup` | | POST | `/internal/fileserver/uploads:cleanup` |
## Status codes ## 상태 코드
| Status | Condition | | 상태 | 조건 |
|---:|---| |---:|---|
| `200` | metadata, full GET, batch result, move | | `200` | metadata, 전체 GET, batch 결과, move |
| `201` | file or upload created | | `201` | 파일이나 업로드를 만들었다 |
| `202` | verification or physical cleanup deferred | | `202` | 검증이나 물리 정리를 미뤘다 |
| `204` | append, cancel, bodyless update | | `204` | 이어 쓰기, 취소, 본문 없는 갱신 |
| `206` | satisfiable Range | | `206` | 만족할 수 있는 Range |
| `304` | validator matched on GET or HEAD | | `304` | GET이나 HEAD에서 validator가 맞았다 |
| `400` | malformed header or header combination | | `400` | 헤더나 헤더 조합이 잘못됐다 |
| `401` | unauthenticated | | `401` | 인증하지 않았다 |
| `403` / `404` | denied, or hidden under the existence-hiding profile | | `403` / `404` | 거부했거나, 존재를 숨기는 profile에서 숨겼다 |
| `409` | state, offset, or lease conflict | | `409` | 상태, offset, lease 충돌 |
| `410` | expired or ended (cancelled, rejected, quarantined) upload resource | | `410` | 만료되거나 끝난(취소, 거부, 격리) 업로드 자원 |
| `411` | `require-content-length` profile with no length | | `411` | `require-content-length` profile인데 길이가 없다 |
| `412` | precondition failed | | `412` | 선행 조건 실패 |
| `413` | size or quota policy violation | | `413` | 크기나 할당량 정책 위반 |
| `415` | upload media type not accepted | | `415` | 업로드 media type을 받지 않는다 |
| `416` | unsatisfiable Range; carries the real length | | `416` | 만족할 수 없는 Range. 실제 길이를 담는다 |
| `422` | digest, signature, or scanner rejection | | `422` | digest, 서명, 검사기 거부 |
| `429` | transfer admission or rate limit | | `429` | 전송 허가나 속도 제한 |
| `460` | tus `Upload-Checksum` does not match that request's bytes; the chunk is discarded and the offset does not move | | `460` | tus `Upload-Checksum`이 그 요청의 바이트와 맞지 않는다. 그 chunk는 버리고 offset은 움직이지 않는다 |
| `503` | storage or scanner unavailable | | `503` | 저장소나 검사기를 쓸 수 없다 |
| `504` | downstream timeout | | `504` | 하류 시간 초과 |
| `507` | out of storage capacity | | `507` | 저장 용량이 없다 |
## Failure body ## 실패 본문
Every failure answers the application's one error shape, the `Envelope` (`application/json`), with 모든 실패는 애플리케이션의 오류 모양 하나인 `Envelope`(`application/json`)로 답한다. 안정된 code, 그 분류,
the stable code, its category, the shared Korean client message for that category and the 그 분류에 대한 공용 한국어 client 메시지, 그리고 `error.details`의 식별 값을 담는다.
identifying values in `error.details`:
```json ```json
{ {
@@ -94,40 +92,37 @@ identifying values in `error.details`:
} }
``` ```
`details` carries only what the failure context holds: `fileId`, `uploadId`, `expectedOffset`, `details`는 실패 context가 가진 것만 담는다: `fileId`, `uploadId`, `expectedOffset`, `currentOffset`, `state`,
`currentOffset`, `state`, and the flags `ambiguous` and `reconciliationRequired` when they are true. 그리고 참일 때만 `ambiguous`와 `reconciliationRequired` flag. 서버 쪽 예외 메시지는 절대 나오지 않는다.
The server-side exception message never appears. `ambiguous` is the field a client must read before `ambiguous`는 client가 재시도 전에 읽어야 하는 필드다. 결과를 모르는 실패는 이미 효과가 났을 수 있다.
retrying: an ambiguous failure may already have taken effect. `retryable` is this occurrence's `retryable`은 이번 발생에 대한 판단이고, 그 code가 허락하는 범위보다 넓어지지 않는다.
decision and is never wider than the code allows.
A batch upload part that is rejected carries the same `error` object (`code`, `category`, batch 업로드에서 거부된 part는 `results[]` 항목에 같은 `error` 객체(`code`, `category`, `message`,
`message`, `retryable`) in its `results[]` entry. `retryable`)를 담는다.
### Protocol exceptions to the Envelope rule ### Envelope 규칙의 프로토콜 예외
Owner decision 2 keeps one HTTP error shape; the protocol pieces below are not error vocabulary and 소유자 결정 2는 HTTP 오류 모양을 하나로 둔다. 아래 프로토콜 요소는 오류 어휘가 아니므로 프로토콜이 정한
stay as the protocol defines them (owner decision 12): 대로 둔다(소유자 결정 12).
- tus protocol headers (`Tus-Resumable`, `Upload-Offset`, `Upload-Length`, …) on every tus - 성공이든 실패든 모든 tus 응답의 tus 프로토콜 헤더(`Tus-Resumable`, `Upload-Offset`, `Upload-Length`, …).
response, success or failure. - 실패 응답의 `Retry-After`와 만족하지 못한 range의 `Content-Range`(헤더 계약을 본다).
- `Retry-After` and the unsatisfied-range `Content-Range` on a failure (see the header contract). - IETF resumable-upload draft의 offset 불일치 응답(`Draft12UploadController#offsetMismatch`):
- The IETF resumable-upload draft's offset-mismatch response `409 application/problem+json`, `type = https://iana.org/assignments/http-problem-types#mismatching-upload-offset`,
(`Draft12UploadController#offsetMismatch`): `409 application/problem+json` with `expectedOffset`과 `providedOffset`. Envelope가 아닌 실패 본문은 이것 하나뿐이다.
`type = https://iana.org/assignments/http-problem-types#mismatching-upload-offset`,
`expectedOffset` and `providedOffset`. It is the only non-Envelope failure body.
## Header contract ## 헤더 계약
| Header | Contract | | 헤더 | 계약 |
|---|---| |---|---|
| `Content-Type` | client value is a claim; the verified type is stored separately | | `Content-Type` | client 값은 주장일 뿐이다. 검증한 형식은 따로 저장한다 |
| `Content-Disposition` | `attachment` by default; scriptable types are never inline | | `Content-Disposition` | 기본은 `attachment`. 스크립트가 될 수 있는 형식은 절대 inline이 아니다 |
| `Accept-Ranges` | `bytes` | | `Accept-Ranges` | `bytes` |
| `Range` | single range by default; multi-range only under an explicit budget | | `Range` | 기본은 범위 하나. 여러 범위는 명시적 예산이 있을 때만 |
| `Content-Range` | actual range on `206`; the unsatisfied form on `416` | | `Content-Range` | `206`에서는 실제 범위, `416`에서는 만족하지 못한 형태 |
| `ETag` | strong validator derived from the SHA-256 | | `ETag` | SHA-256에서 만든 strong validator |
| `Last-Modified` | metadata publication instant, never a filesystem timestamp | | `Last-Modified` | metadata 게시 시각. 파일 시스템 timestamp가 아니다 |
| `Cache-Control` | `private, no-store` by default | | `Cache-Control` | 기본은 `private, no-store` |
| `X-Content-Type-Options` | always `nosniff` on a download | | `X-Content-Type-Options` | 다운로드에는 늘 `nosniff` |
| `Retry-After` | on retryable `409`, `429`, `503`, and `504` | | `Retry-After` | 재시도할 수 있는 `409`, `429`, `503`, `504`에 붙인다 |
| `X-Accel-Redirect` | internal only; never forwarded to a client | | `X-Accel-Redirect` | 내부 전용. client에게 넘기지 않는다 |
+66 -76
View File
@@ -1,14 +1,14 @@
# Fileserver runbooks # Fileserver runbook
Each runbook names the exact metric that fires it and the exact command that resolves it. A runbook runbook마다 그것을 시작하게 하는 metric과 그것을 해결하는 명령을 정확히 적는다. 시작 조건이 「누가 알아챘다」인
whose trigger is "someone noticed" is not actionable, so every one below starts from a signal. runbook은 대응할 수 없다. 그래서 아래 runbook은 모두 신호에서 시작한다.
## Storage full ## 저장소 가득 참
**Signal** — `fileserver.quota{result="rejected"}` rising, or `507` responses appearing. **신호** — `fileserver.quota{result="rejected"}`가 오르거나 `507` 응답이 나온다.
Storage capacity is exhausted or the high-water guard tripped. Uploads are rejected before any bytes 저장 용량이 바닥났거나 high-water 보호 장치가 걸렸다. 업로드는 바이트를 쓰기 전에 거부되므로 망가진 것은
are written, so nothing is corrupt; the system is refusing work it cannot complete. 없다. 시스템이 끝낼 수 없는 일을 거절하고 있을 뿐이다.
```bash ```bash
curl -s $ADMIN/internal/fileserver/storage-health | jq '.usedFraction, .usableBytes' curl -s $ADMIN/internal/fileserver/storage-health | jq '.usedFraction, .usableBytes'
@@ -16,71 +16,68 @@ curl -s -X POST "$ADMIN/internal/fileserver/uploads:cleanup?maxItems=500&maxByte
curl -s "$ADMIN/internal/fileserver/orphans?limit=200" | jq '[.[].sizeBytes] | add' curl -s "$ADMIN/internal/fileserver/orphans?limit=200" | jq '[.[].sizeBytes] | add'
``` ```
Drain the cleanup backlog first — it reclaims space the system already knows is dead. Only then cleanup 적체부터 비운다. 시스템이 이미 죽은 것으로 아는 공간을 되찾는다. 그다음에야 고아 맞춰 보기를
consider an orphan reconcile, and start with a dry run. 생각하고, dry run부터 한다.
## Orphan growth ## 고아 객체 증가
**Signal** — `fileserver.cleanup{result="skipped"}` climbing, or the orphan scan returning more **신호** — `fileserver.cleanup{result="skipped"}`가 오르거나, 고아 scan이 돌 때마다 더 많은 객체를 돌려준다.
objects each run.
Physical objects exist with no metadata record pointing at them. This is not immediately dangerous — 물리 객체는 있는데 그것을 가리키는 metadata 기록이 없다. 당장 위험하지는 않다. 아무것도 그것을 내보내지
nothing serves them — but it consumes capacity indefinitely. 않는다. 하지만 용량을 끝없이 먹는다.
```bash ```bash
# Always look first. A reconcile without dryRun=false is a plan, not an action. # 늘 먼저 본다. dryRun=false가 없는 reconcile은 실행이 아니라 계획이다.
curl -s -X POST "$ADMIN/internal/fileserver/orphans:reconcile" \ curl -s -X POST "$ADMIN/internal/fileserver/orphans:reconcile" \
-H 'content-type: application/json' -d '{"limit":100}' | jq '.candidates' -H 'content-type: application/json' -d '{"limit":100}' | jq '.candidates'
# Apply only the fingerprints you were just shown. # 방금 본 fingerprint만 적용한다.
curl -s -X POST "$ADMIN/internal/fileserver/orphans:reconcile" \ curl -s -X POST "$ADMIN/internal/fileserver/orphans:reconcile" \
-H 'content-type: application/json' \ -H 'content-type: application/json' \
-d '{"dryRun":false,"limit":100,"maxBytes":1073741824, -d '{"dryRun":false,"limit":100,"maxBytes":1073741824,
"expectedFingerprints":["<from the dry run>"],"reasonCode":"ORPHAN_GROWTH_RUNBOOK"}' "expectedFingerprints":["<dry run이 보여 준 값>"],"reasonCode":"ORPHAN_GROWTH_RUNBOOK"}'
``` ```
Echoing the fingerprints is the safety property: an object that changed between the scan and the fingerprint를 되돌려 보내는 것이 안전 장치다. scan과 적용 사이에 바뀐 객체는 지우지 않고 건너뛴다.
apply is skipped rather than deleted.
## Verification backlog ## 검증 적체
**Signal** — `fileserver.verification.queue{age_bucket="old"}` non-zero, or files sitting in **신호** — `fileserver.verification.queue{age_bucket="old"}`가 0이 아니거나, 파일이 VERIFYING에 머문다.
VERIFYING.
A verifier is slow or unavailable. Files stay non-public, which is the correct failure direction: a 검증기가 느리거나 쓸 수 없다. 파일은 공개되지 않은 채 남는다. 맞는 실패 방향이다. `RETRY` 판정은 절대
`RETRY` verdict never becomes an `ACCEPT`. `ACCEPT`가 되지 않는다.
```bash ```bash
curl -s $ADMIN/internal/fileserver/capabilities | jq '.storageType' curl -s $ADMIN/internal/fileserver/capabilities | jq '.storageType'
# Once the verifier is healthy, quarantined files can be re-examined individually. # 검증기가 회복되면 격리된 파일을 하나씩 다시 검사할 수 있다.
curl -s -X POST "$ADMIN/internal/fileserver/files/$FILE_ID:reverify" curl -s -X POST "$ADMIN/internal/fileserver/files/$FILE_ID:reverify"
``` ```
Do not clear the backlog by disabling verification. A file that reached READY without an accepting 검증을 꺼서 적체를 비우지 않는다. 받아들이는 판정 없이 READY가 된 파일은 나중에 검증받은 파일과 구분할 수
verdict cannot be distinguished later from one that was verified. 없다.
## NFS ambiguity ## NFS 결과 모름
**Signal** — problem documents carrying `"ambiguous": true`, or **신호** — 실패 Envelope의 `error.details`에 `"ambiguous": true`가 있거나,
`fileserver.transfer.interruption{reason="stale_handle"}`. `fileserver.transfer.interruption{reason="stale_handle"}`이 나온다.
An operation's outcome could not be determined: the response was lost after the write or rename may 연산의 결과를 알 수 없다. 쓰기나 rename이 적용됐을 수 있는데 응답이 사라졌다. 이런 연산은 절대 자동으로
have landed. These are never retried automatically. 재시도하지 않는다.
```bash ```bash
# The recovery queue holds the files awaiting a decision. # 복구 큐에 결정을 기다리는 파일이 있다.
curl -s "$ADMIN/internal/fileserver/uploads/incomplete?limit=100" | jq curl -s "$ADMIN/internal/fileserver/uploads/incomplete?limit=100" | jq
``` ```
Reconciliation compares the physical size and digest against the record and only confirms READY when 맞춰 보기는 물리 크기와 digest를 기록과 비교하고, key·크기·digest·
all four of key, size, digest, and version agree. Anything short of that is reported, never guessed. version 넷이 모두 맞을 때만 READY를 확정한다. 그보다 못한 것은 짐작하지 않고 보고한다.
## PVC remount ## PVC 다시 마운트
**Signal** — startup failure naming "atomic move", "same file store", or "not writable". **신호** — "atomic move", "same file store", "not writable"을 담은 시작 실패.
The volume was remounted somewhere the probe can no longer prove a required capability. The volume이 다른 곳에 다시 마운트돼서 probe가 필수 capability를 더는 증명하지 못한다. 애플리케이션은 원자적으로
application refuses traffic rather than serving from storage it cannot publish to atomically. 게시할 수 없는 저장소로 내보내지 않고 요청을 거부한다.
```bash ```bash
# staging과 content가 같은 파일 저장소(같은 장치 번호)인지 pod 안에서 본다 # staging과 content가 같은 파일 저장소(같은 장치 번호)인지 pod 안에서 본다
@@ -91,11 +88,11 @@ kubectl exec <pod> -- stat -c %d /var/lib/backend/files/staging /var/lib/backend
접근 모드, backend, mount 옵션)을 다시 적고, 인증한 묶음과 비교한다. 하나라도 다르면 그것이 원인이다. 접근 모드, backend, mount 옵션)을 다시 적고, 인증한 묶음과 비교한다. 하나라도 다르면 그것이 원인이다.
인증은 그 차이를 넘어 옮겨지지 않는다. 인증은 그 차이를 넘어 옮겨지지 않는다.
## Nginx delegation failure ## Nginx 위임 실패
**Signal** — `fileserver.download.delegation{delegated="true"}` with client-visible `404`s. **신호** — `fileserver.download.delegation{delegated="true"}`인데 client에게 `404`가 보인다.
The internal location is misconfigured, so the proxy cannot resolve the redirect it was handed. 내부 location 설정이 잘못돼서 프록시가 넘겨받은 redirect를 풀지 못한다.
프록시 설정의 내부 location(기본 `/__files/`)이 아래 「운영 환경이 지켜야 할 조건」을 지키는지 본다. 프록시 설정의 내부 location(기본 `/__files/`)이 아래 「운영 환경이 지켜야 할 조건」을 지키는지 본다.
@@ -103,8 +100,7 @@ The internal location is misconfigured, so the proxy cannot resolve the redirect
curl -s $ADMIN/internal/fileserver/capabilities | jq '.capabilities.delegatedDownload' curl -s $ADMIN/internal/fileserver/capabilities | jq '.capabilities.delegatedDownload'
``` ```
Turning delegation off is a safe immediate mitigation: the application serves the transfer itself, 위임을 끄는 것이 안전한 즉시 완화책이다. 애플리케이션이 직접 전송한다. 느리지만 맞다.
slower but correct.
```bash ```bash
app.fileserver-platform.nginx.enabled=false app.fileserver-platform.nginx.enabled=false
@@ -136,13 +132,12 @@ app.fileserver-platform.nginx.enabled=false
3. 그 volume이 `storage-certification.md`의 인증 항목(같은 파일 저장소, 원자적 rename, `O_EXCL` 생성)을 3. 그 volume이 `storage-certification.md`의 인증 항목(같은 파일 저장소, 원자적 rename, `O_EXCL` 생성)을
통과해야 한다. 기동 때 `FileserverStartupValidator`도 같은 probe를 다시 돌린다. 통과해야 한다. 기동 때 `FileserverStartupValidator`도 같은 probe를 다시 돌린다.
## Cleanup backlog ## 정리 적체
**Signal** — `fileserver.cleanup{result="deferred"}` rising, or reclaimed bytes flat while deletes **신호** — `fileserver.cleanup{result="deferred"}`가 오르거나, 삭제는 계속되는데 회수한 바이트가 평평하다.
continue.
Items are being deferred faster than they drain. The usual cause is an active writer lease still 항목이 비워지는 것보다 빠르게 미뤄진다. 흔한 원인은 아직 살아 있는 writer lease가 staging 객체를 잡고 있는
holding staging objects, which is correct behaviour, not a fault. 것이다. 결함이 아니라 맞는 동작이다.
```bash ```bash
curl -s "$ADMIN/internal/fileserver/uploads/incomplete?limit=100" \ curl -s "$ADMIN/internal/fileserver/uploads/incomplete?limit=100" \
@@ -150,23 +145,21 @@ curl -s "$ADMIN/internal/fileserver/uploads/incomplete?limit=100" \
curl -s -X POST "$ADMIN/internal/fileserver/uploads:cleanup?maxItems=500&maxBytes=10737418240" curl -s -X POST "$ADMIN/internal/fileserver/uploads:cleanup?maxItems=500&maxBytes=10737418240"
``` ```
If the deferrals are all `ACTIVE_WRITER_LEASE`, the backlog resolves itself as those uploads expire. 미룬 이유가 모두 `ACTIVE_WRITER_LEASE`면 그 업로드들이 만료되면서 적체는 스스로 풀린다. 적체를 비우려고
Never delete staging content to clear a backlog: an upload that is mid-flight will corrupt. staging content를 지우지 않는다. 진행 중인 업로드가 망가진다.
## Namespace quota drift ## Namespace 할당량 어긋남
**Signal** — a namespace's usage (`fileserver.quota` rejections, or the drift query below) disagrees **신호** — namespace의 사용량(`fileserver.quota` 거부, 또는 아래 drift query)이 그 파일들이 실제로 가진 바이트와
with the bytes its files actually hold. The known cause is history: before the 2026-11 maturity 다르다. 알려진 원인은 이력이다. 2026-11 성숙도 리뷰 전에는 `move`가 파일을 옮기면서 할당량은 옮기지 않았다.
review, `move` relocated a file without moving its quota. The bytes of every file moved before that 그 수정 전에 옮긴 파일의 바이트는 아직 떠나온 namespace에 잡혀 있다. 그런 파일을 지우면 지금 있는 namespace에서
fix are still booked on the namespace it left, and deleting such a file reclaims from the namespace 회수한다. 그 회수는 그 namespace의 다른 파일 몫을 최신 것부터 깎거나 0에서 멈추고, 어느 쪽이든 옛 몫은
it now lives in: the reclaim draws down the bookings of that namespace's other files, newest first, 남는다. 그 수정을 받기 전에 namespace를 넘어 파일을 옮긴 파생 서비스에는 이 어긋남이 있다. 그런 적이 없는
or stops at zero, and the old booking stays behind either way. A derived 서비스에는 없어야 한다.
service that moved files across namespaces before taking the fix has this drift; one that never did
should see none.
What the ledger must equal: quota is committed when a file is published and reclaimed when cleanup ledger가 같아야 하는 값: 할당량은 파일을 게시할 때 확정하고 cleanup이 content를 지울 때 회수한다. 그래서
deletes its content, so a namespace's committed bytes are the sizes of its published files that are namespace의 확정 바이트는 아직 `DELETED`가 아닌 게시된 파일 크기의 합이다. 아래 query가 둘을 비교한다.
not yet `DELETED`. The query compares the two and changes nothing. 아무것도 바꾸지 않는다.
```sql ```sql
WITH booked AS ( WITH booked AS (
@@ -188,18 +181,15 @@ SELECT coalesce(b.namespace, h.namespace) AS namespace,
WHERE coalesce(b.booked_bytes, 0) <> coalesce(h.held_bytes, 0); WHERE coalesce(b.booked_bytes, 0) <> coalesce(h.held_bytes, 0);
``` ```
A positive `drift_bytes` is booked capacity no file holds (the namespace a file left); a negative one `drift_bytes`가 양수면 어떤 파일도 갖지 않은 잡힌 용량이다(파일이 떠나온 namespace). 음수면 아무도 잡지 않은
is held content nothing booked (the namespace it arrived in). While uploads, copies, moves or content다(파일이 도착한 namespace). 업로드, copy, move, cleanup이 도는 동안에는 진행 중인 일 때문에 어긋남이
cleanup run, a row can show a drift that only means work in flight, so judge drift with the 보일 수 있다. 그러니 fileserver 쓰기를 멈춘 상태에서 판단한다.
fileserver's writes stopped.
To correct a namespace, stop every fileserver write to it first — uploads, copy, move, delete, and namespace를 바로잡으려면 먼저 그 namespace로 가는 fileserver 쓰기를 모두 멈춘다. 업로드, copy, move, delete,
the cleanup worker (`APP_FILESERVER_PLATFORM_CLEANUP_ENABLED=false`) — because the statement below 그리고 cleanup worker(`APP_FILESERVER_PLATFORM_CLEANUP_ENABLED=false`)다. 아래 문은 `fs_file`에서 다시 계산하므로,
recomputes from `fs_file` and a publish or reclaim that lands between its two steps would be lost. 두 단계 사이에 들어온 게시나 회수는 사라진다. 이 문은 그 namespace의 확정 행을 0으로 만들고, 다시 계산한 합계를
It zeroes the namespace's committed rows and books the recomputed total as one row, shaped the way a 게시가 남기는 모양의 행 하나로 잡는다(`COMMITTED`, `reserved_bytes` 0, 바이트는 `committed_bytes`). 회수가 행을
publish leaves one (`COMMITTED`, `reserved_bytes` 0, the bytes in `committed_bytes`); the per-row 깎은 뒤에는 행별 나눔에 의미가 없고, 강제는 합계만 읽는다. `RESERVED` 행(진행 중인 업로드)은 건드리지 않는다.
split has no meaning once reclaims have drawn rows down, and enforcement only ever reads the sum.
`RESERVED` rows (uploads in progress) are left alone.
```sql ```sql
BEGIN; BEGIN;
@@ -221,5 +211,5 @@ SELECT gen_random_uuid(), 'namespace', :'namespace', 0, held,
COMMIT; COMMIT;
``` ```
Run it with `psql -v namespace=<name>`, then run the drift query again: the namespace must be gone `psql -v namespace=<name>`으로 돌리고 drift query를 다시 돌린다. 쓰기를 다시 열기 전에 그 namespace가 결과에서
from its result before writes resume. 사라져야 한다.
+53 -58
View File
@@ -1,83 +1,78 @@
# Fileserver security model # Fileserver 보안 모델
## The rule everything else follows ## 나머지가 모두 따르는 규칙
Uploaded content is attacker-controlled. Every guard below exists because some part of the request 올라온 content는 공격자가 정한다. 아래 보호 장치는 모두 요청의 어떤 부분(파일 이름, 선언한 media type,
— the filename, the declared media type, the range, the offset — is a value the caller chose. range, offset)이 호출자가 고른 값이기 때문에 있다.
## Path safety ## 경로 안전
A client value never becomes a path. The physical key is server-generated, and `ContentKey`'s client 값은 절대 경로가 되지 않는다. 물리 key는 서버가 만들고, `ContentKey`의 글자 집합에는 `.`이 아예 없다.
character class excludes `.` entirely, so no traversal or extension-shaped segment survives 그래서 경로 거슬러 오르기나 확장자 모양의 조각은 검증을 통과하지 못한다. 식별자가 `Path`가 되는 곳은
validation. `DefaultPhysicalPathResolver` is the only place an identifier becomes a `Path`, and it `DefaultPhysicalPathResolver` 하나다. 입력을 믿지 않고, 만든 뒤 정규화해서 root 안에 있는지 다시 확인한다.
normalizes and re-checks containment after construction rather than trusting the input.
Symlink refusal happens at open time, not only at construction. A parent directory can be replaced symlink 거부는 경로를 만들 때만이 아니라 열 때도 한다. 그 사이에 부모 폴더가 바뀔 수 있으므로, 경로를 만들
between the two, so a check that ran only at path-building time would be a race, not a guard. 때만 검사하면 보호 장치가 아니라 경쟁 조건이다.
## Filename handling ## 파일 이름 처리
`OriginalFilenamePolicy` strips path separators, NUL, quoting characters, and the colon — the last `OriginalFilenamePolicy`는 경로 구분자, NUL, 따옴표 문자, 콜론을 지운다. 콜론은 Windows에서 드라이브 참조와
because on Windows it opens both a drive reference and an NTFS alternate data stream, so a name that NTFS alternate data stream을 모두 열기 때문에, 슬래시를 지워도 콜론이 남으면 여전히 경로 모양이다. 제어
keeps it is still path-shaped after the slashes are gone. Control characters and bidirectional 문자와 양방향 override를 지우고, 이어진 점을 하나로 줄이고, 예약된 장치 이름을 막고, 결과를 UTF-8 바이트로
overrides are removed, dot runs collapsed, reserved device names guarded, and the result is bounded 제한한다.
in UTF-8 bytes.
The sanitized name is display data. It is never used to build a key, and it reaches a header only 정리한 이름은 표시용 데이터다. key를 만드는 데 절대 쓰지 않는다. 헤더에는 `HttpContentDispositionFactory`를
through `ContentDispositionFactory`, which restricts the ASCII form and percent-encodes the UTF-8 거쳐서만 들어가고, 이것이 ASCII 형태를 제한하고 UTF-8 형태를 percent-encoding한다.
form.
## Content type ## Content 형식
The client's `Content-Type` is stored as a claim. The verified type comes from the verification client의 `Content-Type`은 주장으로 저장한다. 검증한 형식은 검증 pipeline에서 오고, 검증한 형식만 내보낸다.
pipeline, and only the verified type is served. A claimed type that contradicts the content is content와 어긋나는 주장 형식은 고치지 않고 격리한다.
quarantined rather than corrected.
Scriptable types are never served inline, whatever the caller asked for: serving stored HTML or SVG 스크립트가 될 수 있는 형식은 호출자가 무엇을 요청했든 절대 inline으로 내보내지 않는다. 업로드 origin에서
inline from an upload origin is a stored cross-site scripting primitive. Every download also carries 저장된 HTML이나 SVG를 inline으로 내보내면 stored cross-site scripting의 재료가 된다. 모든 다운로드는
`X-Content-Type-Options: nosniff`. `X-Content-Type-Options: nosniff`도 붙인다.
## Verification precedence ## 검증 우선순위
`REJECT > QUARANTINE > RETRY > ACCEPT`. A verifier that times out or throws is `RETRY`, never a `REJECT > QUARANTINE > RETRY > ACCEPT`. 시간 초과나 예외를 낸 검증기는 `RETRY`이고 조용한 통과가 아니다.
silent pass, and an empty verifier chain answers `RETRY` rather than accepting. A file becomes 검증기가 하나도 없으면 받아들이지 않고 `RETRY`로 답한다. 파일은 `ACCEPT` 뒤에야 공개로 읽을 수 있다.
publicly readable only after an `ACCEPT`.
## Range safety ## Range 안전
The range budget is enforced before content is opened, so a request naming many ranges is rejected range 예산은 content를 열기 전에 강제한다. 그래서 range를 많이 적은 요청은 저장소 작업을 불리지 않고
without amplifying into storage work. An unsatisfiable range answers `416` with the real length and 거부된다. 만족할 수 없는 range는 실제 길이를 담은 `416`으로 답하고 아무것도 열지 않는다.
opens nothing.
## Authorization ## 권한
Every public operation calls the injected `FileAccessPolicyPort` before any quota reservation or storage 모든 공개 연산은 할당량 예약이나 저장소 변경 전에 주입한 `FileAccessPolicyPort`를 부른다. 그래서 거부하면
mutation, so a denial leaves no record, no reservation, and no staging object. Finalize is 기록도, 예약도, staging 객체도 남지 않는다. finalize는 `FINALIZE`로, management plane 읽기는 `ADMIN_READ`로
authorized as `FINALIZE`, and management-plane reads as `ADMIN_READ`. Startup refuses to run a 권한을 본다. 시작 단계는 모두 허락하는 정책으로 운영 profile을 돌리는 것을 거부한다.
production profile with an allow-all policy.
Each file records its owner: the principal that created it and, when the transport resolved one, 파일마다 소유자를 기록한다. 그 파일을 만든 principal, 그리고 transport가 하나를 풀었다면 그 tenant(`tenant`
its tenant (the `tenant` subject attribute). The default role policy grants an operation on an subject 속성)다. 기본 role 정책은 이미 있는 파일에 대한 연산을 같은 tenant의 소유자에게만 허락한다. 그래서
existing file only to its owner in the same tenant, so two callers holding the same role cannot 같은 role을 가진 두 호출자도 서로의 파일을 읽거나, 다운로드하거나, finalize하거나, 지우거나, copy하거나,
read, download, finalize, delete, copy or move each other's files. An admin role does not bypass move할 수 없다. admin role도 이것을 건너뛰지 않는다. 다른 호출자의 파일을 다루라고 감사하는 management
this — acting on another caller's file is what the audited management plane is for. A file created plane이 있다. 소유자를 기록하기 전(마이그레이션 V5)에 만든 파일은 소유자가 없고 management plane으로만 닿는다.
before ownership was recorded (migration V5) has no owner and is reachable only through the
management plane. Anonymous read, when enabled, publishes every file and skips the owner check.
## Delegation 익명 읽기는 설정으로 켤 수 없다([configuration.md](configuration.md) 「권한」). `role-based` 정책은 늘 끈 채로
만든다. `RoleBasedFileAccessPolicy`를 직접 만들면서 익명 읽기를 켜면 모든 파일을 공개하고 소유자 검사를
건너뛴다.
`X-Accel-Redirect` is emitted only after authorization and the READY gate, and only for a full, ## 위임
unconditional response. The internal prefix must be an `internal` Nginx location; the front proxy
also strips any client-supplied delegation header so a caller cannot name an internal object. `X-Accel-Redirect`는 권한 확인과 READY 관문을 지난 뒤, 조건 없는 전체 응답에만 내보낸다. 내부 접두사는
Nginx의 `internal` location이어야 한다. 프런트 프록시는 client가 보낸 위임 헤더도 지워서 호출자가 내부 객체를
가리키지 못하게 한다.
## Telemetry ## Telemetry
No metric label, span attribute, or audit record carries a file id, upload id, filename, path, or metric label, span 속성, 감사 기록 어디에도 file id, upload id, 파일 이름, 경로, user id를 담지 않는다.
user id. Where correlation is needed the value is a keyed HMAC fingerprint — keyed because the 상관관계가 필요한 곳은 key를 쓴 HMAC fingerprint를 쓴다. 식별자 공간은 셀 수 있으므로 key 없는 digest는
identifier space is enumerable and an unkeyed digest of it is reversible by brute force. 전수 대입으로 되돌릴 수 있다. 그래서 key가 필요하다.
## Ambiguous failures ## 결과를 모르는 실패
A failure whose operation may already have taken effect is reported as ambiguous and is never 연산이 이미 효과를 냈을 수 있는 실패는 결과를 모르는 것(ambiguous)으로 보고하고 절대 재시도할 수 있다고 하지
retryable. On a network filesystem a lost response is indistinguishable from a rejection at the 않는다. 네트워크 파일 시스템에서는 사라진 응답과 socket 수준의 거부를 구분할 수 없다. 그래서 안전하다고
socket level, so anything not provably safe is treated as ambiguous and sent to reconciliation. 증명할 수 없는 것은 모두 결과를 모르는 것으로 보고 맞춰 보기로 보낸다.
+29 -31
View File
@@ -1,23 +1,22 @@
# Storage certification # 저장소 인증
## Why a certification is per-volume ## 인증이 volume마다인 이유
Atomic rename, same-file-store guarantees, and symlink refusal are properties of a specific 원자적 rename, 같은 파일 저장소 보장, symlink 거부는 「Kubernetes」나 「PVC」의 성질이 아니라 특정 mount 뒤의
filesystem behind a specific mount — not of "Kubernetes" or "a PVC". Change the CSI driver, the 특정 파일 시스템의 성질이다. CSI driver, StorageClass, 접근 모드, backend, mount 옵션 중 하나만 바꿔도 그중
StorageClass, the access mode, the backend, or the mount options and any of them can differ. A 무엇이든 달라질 수 있다. 다섯을 모두 적지 않은 인증은 다른 곳으로 옮길 수 없다.
certification that does not name all five is not transferable.
## What is certified ## 인증하는 것
| Property | Why it matters | | 성질 | 중요한 이유 |
|---|---| |---|---|
| Same file store for staging and content | A rename across stores is a copy, so publication stops being atomic. | | staging과 content가 같은 파일 저장소 | 저장소를 넘는 rename은 복사라서 게시가 원자적이지 않게 된다. |
| Atomic rename | The publish path's default strategy. | | 원자적 rename | 게시 경로의 기본 전략이다. |
| Atomic create (`O_EXCL`) | Makes a publish create-only rather than a silent overwrite. | | 원자적 생성(`O_EXCL`) | 게시를 조용한 덮어쓰기가 아니라 새로 만들기만 하게 한다. |
| Symlink refusal | Stops a replaced parent from redirecting a write outside the root. | | symlink 거부 | 바뀐 부모 폴더가 쓰기를 root 밖으로 돌리는 것을 막는다. |
| Ranged read | The download contract depends on it. | | 범위 읽기 | 다운로드 계약이 기댄다. |
## Running the certification ## 인증 돌리기
이 repo는 인증 job 매니페스트를 두지 않는다(2026-11-07 소유자 결정). 배포하는 쪽이 대상 volume을 저장 이 repo는 인증 job 매니페스트를 두지 않는다(2026-11-07 소유자 결정). 배포하는 쪽이 대상 volume을 저장
루트(`/var/lib/backend/files`)에 마운트한 일회성 pod에서 아래를 차례로 확인한다. 루트(`/var/lib/backend/files`)에 마운트한 일회성 pod에서 아래를 차례로 확인한다.
@@ -45,31 +44,30 @@ certification that does not name all five is not transferable.
2번이 실패하면 인증하지 않는다. staging과 content가 다른 저장소인 volume은 게시가 소리 없이 복사로 바뀐다. 2번이 실패하면 인증하지 않는다. staging과 content가 다른 저장소인 volume은 게시가 소리 없이 복사로 바뀐다.
## Network filesystems ## 네트워크 파일 시스템
```bash ```bash
docker compose -f src/adapter/outbound/fileserver/compose/nfs/compose.yml up -d docker compose -f src/adapter/outbound/fileserver/compose/nfs/compose.yml up -d
FILESERVER_NFS_TESTS=true ./gradlew :adapter:outbound:fileserver:test FILESERVER_NFS_TESTS=true ./gradlew :adapter:outbound:fileserver:test
``` ```
The mount is `hard`, deliberately. A `soft` mount converts a slow server into a short write, which mount는 일부러 `hard`다. `soft` mount는 느린 서버를 짧게 끝난 쓰기로 바꾼다. 이 설계가 받아들이지 않는 바로
is exactly the corruption this design refuses to accept. 그 손상이다.
## Startup enforcement ## 시작 때 강제
`FileserverStartupValidator` re-runs the probe at boot and refuses to accept traffic when a required `FileserverStartupValidator`가 부팅 때 probe를 다시 돌리고, 필수 capability가 없으면 요청을 받지 않는다.
capability is missing — `ATOMIC_MOVE_REQUIRED` on a filesystem that cannot prove an atomic move 원자적 move를 증명하지 못하는 파일 시스템에 `ATOMIC_MOVE_REQUIRED`를 두면 조용히 기능을 줄이지 않고 닫힌
fails closed rather than degrading silently. 쪽으로 실패한다.
## Adding a new store ## 새 저장소 더하기
Pass two executable contracts. A prose claim of compatibility is not accepted. 실행되는 계약 둘을 통과해야 한다. 글로 쓴 호환 주장은 받지 않는다.
- `UploadStoragePortContract` — the application port's contract, in `application-fileserver` - `UploadStoragePortContract` — 애플리케이션 port의 계약이다. `application-fileserver` testFixtures에 있다
testFixtures (`testImplementation testFixtures(project(':application-fileserver'))`). The (`testImplementation testFixtures(project(':application-fileserver'))`). 애플리케이션의
application's `FakeUploadStorageGateway` extends it too, so use case tests and the real store obey `FakeUploadStorageGateway`도 이것을 상속한다. 그래서 use case 테스트와 실제 저장소가 같은 offset, chunk
the same offset, chunk-checksum and size-ceiling rules (a declared 0-byte upload refuses its first checksum, 크기 상한 규칙을 지킨다(0바이트로 선언한 업로드는 첫 바이트를 거부한다).
byte). - `ContentStoreContract` — 로컬 어댑터의 내부 `BlockingContentStore` SPI 계약이다. 이 어댑터의 테스트에 있다.
- `ContentStoreContract` — the local adapter's internal `BlockingContentStore` SPI, in this 그 SPI는 일부러 어댑터 안에 둔다(리뷰 S1-#12: 애플리케이션은 그것을 부르지 않는다). 그래서 계약도 어댑터에
adapter's tests. That SPI stays in the adapter by design (review S1-#12: the application never 있다. 그 SPI를 다시 쓰는 저장소도 이것을 상속한다.
calls it), so its contract stays with it; a store that reuses the SPI extends it as well.
+50 -52
View File
@@ -1,71 +1,69 @@
# Fileserver support matrix # Fileserver 지원 매트릭스
A support level here is a claim about evidence, not about intent. Every row names the CI job that 여기의 지원 등급은 의도가 아니라 증거에 대한 주장이다. 행마다 그 증거를 만드는 CI job을 적는다. 행이 없는
produces that evidence; `FileserverDocumentationCoverageTest` fails the build if a row names a job job을 적으면 `FileserverDocumentationCoverageTest`가 빌드를 실패시킨다. 그래서 등급은 그것을 정당화한 테스트보다
that does not exist, so a level can never outlive the test that justified it. 오래 살 수 없다.
## Levels ## 등급
| Level | What it means | 등급 이름은 원문 그대로 쓴다. 표와 테스트가 이 이름을 그대로 읽는다.
| 등급 | 뜻 |
|---|---| |---|---|
| Stable | Certified on every pull request. Contract changes are breaking changes. | | Stable | pull request마다 인증한다. 계약 변경은 깨지는 변경이다. |
| Beta | Certified nightly. The contract may still change with a deprecation notice. | | Beta | 매일 밤 인증한다. 폐기 예고와 함께 계약이 아직 바뀔 수 있다. |
| Limited | Certified on the release gate only, under stated constraints. | | Limited | 밝힌 제약 아래에서 릴리스 게이트에서만 인증한다. |
| Compatibility | Accepted but not optimized; known caveats are listed inline. | | Compatibility | 받아들이지만 최적화하지 않는다. 알려진 주의점은 그 자리에 적는다. |
| Experimental | Off by default, unratified upstream, may change without notice. | | Experimental | 기본으로 꺼져 있고, 상위 표준이 확정되지 않았으며, 예고 없이 바뀔 수 있다. |
## Runtime profiles ## 런타임 profile
| Profile | Level | CI job | | Profile | 등급 | CI job |
|---|---|---| |---|---|---|
| Local filesystem (ext4) content store | Stable | `fileserver-local-ext4-contract` | | 로컬 파일 시스템(ext4) content 저장소 | Stable | `fileserver-local-ext4-contract` |
| Spring MVC transport (raw, multipart, batch, download) | Stable | `fileserver-http-contract` | | Spring MVC transport(raw, multipart, batch, 다운로드) | Stable | `fileserver-http-contract` |
| Path, filename, range, and problem-detail hardening | Stable | `fileserver-security-suite` | | 경로, 파일 이름, range, problem-detail 강화 | Stable | `fileserver-security-suite` |
| Bounded-memory transfer | Stable | `fileserver-bounded-memory` | | 메모리 상한이 있는 전송 | Stable | `fileserver-bounded-memory` |
| Application and architecture invariants | Stable | `fileserver-unit-and-architecture` | | 애플리케이션·아키텍처 불변식 | Stable | `fileserver-unit-and-architecture` |
| Runtime assembly (the capability starts with the flag on) | Stable | `fileserver-unit-and-architecture` | | 런타임 조립(flag를 켜면 capability가 시작한다) | Stable | `fileserver-unit-and-architecture` |
| tus 1.0 resumable uploads | Stable | `fileserver-http-contract` | | tus 1.0 이어 올리기 업로드 | Stable | `fileserver-http-contract` |
| Crash-recovery matrix | Beta | `fileserver-process-kill-matrix` | | 장애 복구 매트릭스 | Beta | `fileserver-process-kill-matrix` |
| NFSv4 ambiguity handling | Beta | `fileserver-nfs-ambiguity` | | NFSv4 결과 모름 처리 | Beta | `fileserver-nfs-ambiguity` |
| Large-file and slow-client performance | Beta | `fileserver-large-file-performance` | | 큰 파일·느린 client 성능 | Beta | `fileserver-large-file-performance` |
| Multi-instance writer lease | Beta | `fileserver-multi-instance-lease` | | 여러 인스턴스 writer lease | Beta | `fileserver-multi-instance-lease` |
| Nginx `X-Accel-Redirect` delegation | Limited | `fileserver-http-contract` | | Nginx `X-Accel-Redirect` 위임 | Limited | `fileserver-http-contract` |
| Telemetry sensitive-data suppression | Stable | `fileserver-sensitive-telemetry-scan` | | telemetry 민감 데이터 억제 | Stable | `fileserver-sensitive-telemetry-scan` |
| Documentation and support-claim coverage | Stable | `fileserver-documentation-gate` | | 문서와 지원 주장 범위 | Stable | `fileserver-documentation-gate` |
| Full release verification | Stable | `fileserver-full-verification` | | 전체 릴리스 검증 | Stable | `fileserver-full-verification` |
| HTTP resumable uploads draft-12 | Experimental | `fileserver-http-contract` | | HTTP resumable uploads draft-12 | Experimental | `fileserver-http-contract` |
### WebFlux transport removed ### WebFlux transport 제거
The reactive router and handlers (`web.fileserver.reactive`) were removed on 2026-09-25 (D4: the reactive router와 handler(`web.fileserver.reactive`)는 2026-09-25에 지웠다(D4: 템플릿은 virtual thread 위의
template is servlet on virtual threads). The shipped composition could never select them — the web servlet이다). 내보낸 조립은 그것을 고를 수 없었다. web leaf가 `DispatcherServlet`을 classpath에 두므로 Boot는
leaf puts `DispatcherServlet` on the classpath, so Boot resolves SERVLET. SERVLET으로 정한다.
## Explicitly not claimed ## 주장하지 않는 것
These have no job, and therefore no claim: 아래는 job이 없고, 그래서 주장도 없다.
- Kubernetes PVC(ReadWriteOnce 포함). 이 repo는 클러스터 매니페스트와 그것을 검사하던 release job을 - Kubernetes PVC(ReadWriteOnce 포함). 이 repo는 클러스터 매니페스트와 그것을 검사하던 release job을
2026-11-07에 지웠다. volume이 지켜야 할 조건은 [operations.md](operations.md) 「운영 환경이 지켜야 할 2026-11-07에 지웠다. volume이 지켜야 할 조건은 [operations.md](operations.md) 「운영 환경이 지켜야 할
조건」, 인증 절차는 [storage-certification.md](storage-certification.md)다. 클러스터 결과는 배포하는 쪽이 조건」, 인증 절차는 [storage-certification.md](storage-certification.md)다. 클러스터 결과는 배포하는 쪽이
만든다. 만든다.
- Kubernetes ReadWriteMany PVC. 여러 노드의 동시 쓰기는 인증하지 않았다.
- 운영 저장 루트로서의 Windows NTFS. 파일 이름 정책이 NTFS가 예약한 문자를 지우지만, 그 위의 게시 경로를
인증하는 job은 없다.
- content 저장소로서의 object storage. 계약(`ContentStoreContract`)은 있지만 아직 구현한 어댑터가 없다.
- 서버 쪽 악성 코드 검사. 검증 pipeline에 port와 판정 우선순위는 있지만 내놓는 검사기는 없다.
- Kubernetes ReadWriteMany PVC. Concurrent writers across nodes are not certified. ## 나머지가 적힌 곳
- Windows NTFS as a production storage root. The filename policy strips the characters NTFS
reserves, but no job certifies the publish path there.
- Object storage as a content store. The contract exists (`ContentStoreContract`) but no adapter
implements it yet.
- Server-side malware scanning. The verification pipeline has the port and the verdict precedence;
no scanner is shipped.
## Where the rest is written down - [configuration.md](configuration.md) — 모든 `app.fileserver-platform.*` key, 그 기본값, 기능을 줄이지 않고
시작을 실패시키는 조건.
- [configuration.md](configuration.md) — every `app.fileserver-platform.*` key, its default, and the - [design-deviations.md](design-deviations.md) — 구현이 고정된 설계와 다른 곳, 그 이유, 결정마다 고정하는 테스트.
conditions that fail startup rather than degrade. - [http-contract.md](http-contract.md) — wire 계약.
- [design-deviations.md](design-deviations.md) — where the implementation departs from the frozen - [security.md](security.md) — 위협 모델과 각 통제를 강제하는 것.
design, why, and the test that pins each decision. - [operations.md](operations.md) — 각각 metric에서 시작하는 runbook.
- [http-contract.md](http-contract.md) — the wire contract. - [storage-certification.md](storage-certification.md) — volume을 인증하는 법.
- [security.md](security.md) — the threat model and what enforces each control. - [upgrade-guide.md](upgrade-guide.md) — 버전 사이에 바뀌는 것.
- [operations.md](operations.md) — runbooks, each starting from a metric.
- [storage-certification.md](storage-certification.md) — how a volume is certified.
- [upgrade-guide.md](upgrade-guide.md) — what changes between versions.
+37 -38
View File
@@ -1,9 +1,9 @@
# Fileserver upgrade guide # Fileserver 업그레이드 안내
## Enabling the capability ## Capability 켜기
The Fileserver ships off. Nothing is registered — no endpoint, no thread pool, no metric — until it Fileserver는 꺼진 채로 나온다. 명시적으로 켜기 전에는 아무것도 등록하지 않는다. endpoint도, 스레드 pool도,
is enabled explicitly. metric도 없다.
```yaml ```yaml
app: app:
@@ -15,68 +15,67 @@ app:
fingerprint-key: ${FILESERVER_FINGERPRINT_KEY} fingerprint-key: ${FILESERVER_FINGERPRINT_KEY}
``` ```
`instance-id` must be unique per instance: it is the writer-lease owner, and two nodes sharing one `instance-id`는 인스턴스마다 달라야 한다. writer lease의 소유자이기 때문이다. 두 노드가 같은 값을 쓰면 둘 다
would both believe they hold the same lease. 같은 lease를 가졌다고 믿는다.
`fingerprint-key` is required and has no default. Startup fails without it rather than falling back `fingerprint-key`는 필수이고 기본값이 없다. 없으면 key 없는 digest로 물러서지 않고 시작이 실패한다. 셀 수
to an unkeyed digest, which would be reversible for an enumerable identifier space. 있는 식별자 공간에서 key 없는 digest는 되돌릴 수 있다.
## Optional surfaces ## 선택 면
Each is a separate switch, and each defaults to off: 각각 따로 된 스위치이고, 모두 기본으로 꺼져 있다.
```yaml ```yaml
app: app:
fileserver-platform: fileserver-platform:
admin: admin:
enabled: false # management plane; intended for a management port enabled: false # management plane. 관리 port에 둔다
tus: tus:
enabled: false # tus 1.0 Stable enabled: false # tus 1.0, Stable
httpbis-draft12: httpbis-draft12:
enabled: false # Experimental; unratified, may change without notice enabled: false # Experimental. 표준 미확정, 예고 없이 바뀔 수 있다
nginx: nginx:
enabled: false # front-proxy delegation; needs a validated internal location enabled: false # 프런트 프록시 위임. 검증한 internal location이 필요하다
``` ```
## Database schema ## DB schema
The metadata schema is installed as a capability migration and starts inactive: metadata schema는 capability 마이그레이션으로 설치되고 비활성 상태로 시작한다.
``` ```
V1__create_fileserver_metadata.sql → capability_schema_registry: jpa-fileserver-metadata-v1 V1__create_fileserver_metadata.sql → capability_schema_registry: jpa-fileserver-metadata-v1
``` ```
Activate it deliberately. Enabling the capability without an activated schema fails at startup 의도해서 활성화한다. 활성화한 schema 없이 capability를 켜면 첫 업로드가 아니라 시작 때 실패한다.
rather than at the first upload.
## Choosing a publish mode ## 게시 방식 고르기
| Mode | When | | 방식 | 언제 |
|---|---| |---|---|
| `atomic-move-preferred` | Default. Uses an atomic rename when the probe proves one, else a metadata pointer. | | `atomic-move-preferred` | 기본값. probe가 증명하면 원자적 rename을, 아니면 metadata pointer를 쓴다. |
| `atomic-move-required` | Fail closed. Refuses to start on storage that cannot prove an atomic move. | | `atomic-move-required` | 닫힌 쪽으로 실패한다. 원자적 move를 증명하지 못하는 저장소에서는 시작을 거부한다. |
| `metadata-pointer` | For storage without atomic rename; publication is the metadata commit. | | `metadata-pointer` | 원자적 rename이 없는 저장소용. 게시가 곧 metadata 확정이다. |
Pick `atomic-move-required` when the storage is certified and you want a misconfiguration to surface 저장소를 인증했고 잘못된 설정이 게시 때가 아니라 부팅 때 드러나기를 원하면 `atomic-move-required`를 고른다.
at boot rather than at publish time.
## Behaviour that will surprise you ## 놀랄 만한 동작
- **A delete answers `202`, not `204`, when content still exists.** The file is already unreadable; - **content가 아직 있으면 삭제는 `204`가 아니라 `202`로 답한다.** 파일은 이미 읽을 수 없고, 물리 회수는
the physical reclaim is deferred. Treating `202` as a failure will produce spurious retries. 미뤘다. `202`를 실패로 다루면 쓸데없이 재시도한다.
- **A batch upload answers `200` even when parts failed.** The batch is explicitly non-atomic, and a - **batch 업로드는 part가 실패해도 `200`으로 답한다.** batch는 명시적으로 원자적이지 않고, 상태 코드 하나로는
single status could not report a partial outcome honestly. Read `results[].problem`. 부분 결과를 정직하게 알릴 수 없다. `results[].error`를 읽는다.
- **An ambiguous failure must not be retried.** Check `"ambiguous": true` in the problem document. - **결과를 모르는 실패는 재시도하면 안 된다.** 실패 Envelope의 `error.details`에서 `"ambiguous": true`를 본다.
- **`If-Match` takes the strong ETag, not a version number.** A client can only assert about the - **`If-Match`는 version 숫자가 아니라 strong ETag를 받는다.** client는 실제로 받은 표현에 대해서만 주장할 수
representation it was actually served. 있다.
- **Inline rendering is refused for scriptable types** even when the caller asks for it. - **스크립트가 될 수 있는 형식은 호출자가 요청해도 inline으로 그리지 않는다.**
## Verifying an upgrade ## 업그레이드 확인
```bash ```bash
cd src cd src
./gradlew verifyCleanArchitectureDependencies --console=plain ./gradlew verifyCleanArchitectureDependencies --console=plain
./gradlew :application-core:check :adapter:inbound:web:check \ ./gradlew :application-fileserver:check :adapter:inbound:web-fileserver:check \
:adapter:outbound:fileserver:check --console=plain :adapter:outbound:fileserver:check :adapter:outbound:persistence-fileserver:check \
./gradlew :app-bootstrap:test --tests '*Fileserver*' --console=plain :composition:fileserver-platform:check --console=plain
./gradlew :app-bootstrap:architectureTest --console=plain
``` ```
+171 -183
View File
@@ -1,37 +1,34 @@
# HTTP Client Platform — Configuration Reference # HTTP Client 플랫폼 — 설정 참조
Every outbound call resolves exactly one **Named Client Profile**. The whole capability lives under 모든 외부 호출은 **Named Client Profile**(이름 붙은 client profile) 정확히 하나로 풀린다. capability 전체가
the `app.httpclient` prefix: profiles under `app.httpclient.clients[N]`, Dynamic Target policies `app.httpclient` 접두사 아래에 있다. profile은 `app.httpclient.clients[N]` 아래, Dynamic Target 정책은
under `app.httpclient.dynamic-targets[N]`. `app.httpclient.dynamic-targets[N]` 아래에 있다.
Design §30.1 forbids a production profile from inheriting large framework defaults. Anything a 설계서 §30.1은 운영 profile이 framework의 큰 기본값을 물려받는 것을 금한다. 운영 배포가 정해야 하는 것은
production deployment must decide has either no default or an unusable one, and 기본값이 없거나 쓸 수 없는 기본값을 가진다. `HttpClientStartupValidator`는 짐작하지 않고 context를 실패시킨다.
`HttpClientStartupValidator` fails the context rather than guessing.
## The master switch ## 주 스위치
| Property | Type | Default | Environment | | 속성 | 타입 | 기본값 | 환경 변수 |
|---|---|---|---| |---|---|---|---|
| `app.httpclient.enabled` | boolean | `true` | `APP_HTTPCLIENT_ENABLED` | | `app.httpclient.enabled` | boolean | `true` | `APP_HTTPCLIENT_ENABLED` |
The module is on when present: a service adds `runtimeOnly project(':adapter:outbound:httpclient')` 모듈은 있으면 켜진다. 서비스가 `app-bootstrap/build.gradle`에 `runtimeOnly project(':adapter:outbound:httpclient')`를
to `app-bootstrap/build.gradle`, and the module's own `config/module-defaults/httpclient.yml` (loaded at the lowest 더하면, 모듈 자신의 `config/module-defaults/httpclient.yml`(support leaf의 `ModuleDefaultsEnvironmentPostProcessor`가
precedence by the support leaf's `ModuleDefaultsEnvironmentPostProcessor`) supplies `enabled: true`. Absent from the 가장 낮은 우선순위로 읽는다)이 `enabled: true`를 준다. 빌드에 없는 것이 보통의 꺼진 상태다. `false`는 명시적으로
build is the ordinary off state. `false` is the explicit off: `HttpClientPlatformAutoConfiguration` 끈 것이다. 그러면 `HttpClientPlatformAutoConfiguration`도, 그것이 import하는 것도 처리되지 않는다. 바인딩되는
is then never processed and neither is anything it imports — no property is bound, and no transport 속성이 없고, transport provider, connection pool, TLS context, credential, 스레드, gateway, actuator endpoint도
provider, connection pool, TLS context, credential, thread, gateway or actuator endpoint exists. A 없다. 끈 배포에서는 잘못된 HTTP client 설정이 시작을 실패시키지 않는다.
malformed HTTP client setting cannot fail the startup of a deployment that switched it off.
Anything that is not exactly `true` — `yes`, `1`, blank — turns the platform off. On with no client 정확히 `true`가 아닌 값(`yes`, `1`, 빈 값)은 플랫폼을 끈다. 켰는데 선언한 client가 없으면
declared is a startup failure carrying `HTTPCLIENT_ACTIVE_WITHOUT_CLIENTS`: a platform with nothing `HTTPCLIENT_ACTIVE_WITHOUT_CLIENTS`로 시작이 실패한다. 부를 대상이 없는 플랫폼도 아무 호출자도 닿을 수 없는
to call still holds transport providers and gateways no caller can reach. transport provider와 gateway를 쥐고 있기 때문이다.
## Declaring clients from the environment ## 환경 변수로 client 선언하기
Clients are an indexed list carrying their own `name`, not a map keyed by name. A map key becomes a client는 이름을 key로 한 map이 아니라, 자기 `name`을 가진 index 목록이다. map key는 환경 변수 이름의 한 조각이
segment of the environment variable and the relaxed binder normalises it, so `payment-api` and 되고 relaxed binder가 그것을 정규화한다. 그래서 `payment-api`와 `payment_api`가 한 항목으로 도착하고, 사라진
`payment_api` would arrive as one entry with nothing said about the one that was lost. Both a 쪽에 대해서는 아무 말도 없다. 이름이 겹치거나 정규화한 뒤 겹치면 둘 다 시작이 실패한다.
duplicate name and a name that collides once normalised fail startup.
```dotenv ```dotenv
APP_HTTPCLIENT_ENABLED=true APP_HTTPCLIENT_ENABLED=true
@@ -47,200 +44,194 @@ APP_HTTPCLIENT_DYNAMIC_TARGETS_0_NAME=webhook
APP_HTTPCLIENT_DYNAMIC_TARGETS_0_ALLOWED_SCHEMES_0=https APP_HTTPCLIENT_DYNAMIC_TARGETS_0_ALLOWED_SCHEMES_0=https
``` ```
`docs/httpclient/env-fields.yaml` is the registry of accepted variable names. It is `docs/httpclient/env-fields.yaml`이 받아들이는 변수 이름의 registry다. settings record에서 만들어지고 양쪽
derived from the settings record and held to it in both directions, and the platform refuses to 방향으로 그 record와 대조된다. 플랫폼은 여기 없는 `APP_HTTPCLIENT_` 변수가 있으면 시작을 거부한다. 그래서
start on an `APP_HTTPCLIENT_` variable that is not in it — so `APP_HTTPCLIENT_CLIENTS_0_TIMEUOT_TOTAL_CALL`은 client를 조용히 기본 예산으로 두지 않고 시작을 실패시킨다.
`APP_HTTPCLIENT_CLIENTS_0_TIMEUOT_TOTAL_CALL` fails startup instead of silently leaving the client 환경 변수가 아니라 설정 파일로 준 모르는 key도 같은 이유로 엄격한 바인딩이 거부한다.
on its default budget. Unknown keys supplied through a configuration file rather than the
environment are refused by strict binding for the same reason.
Only `APP_HTTPCLIENT_ENABLED` appears in `src/.env` and `docs/registries/env-keys.yaml`. It is the `src/.env`와 `docs/registries/env-keys.yaml`에는 `APP_HTTPCLIENT_ENABLED`만 있다. 배포와 상관없는 값을 가진
one key with a deployment-independent value; templating an indexed client in `application.yml` would 유일한 key다. index를 단 client를 `application.yml`에 template로 두면 모든 배포에 이름 없는 client가 생기고,
materialise a nameless client in every deployment, which the aggregate validation refuses. 그것은 묶음 검증이 거부한다.
## `app.httpclient.clients[N]` ## `app.httpclient.clients[N]`
| Property | Type | Default | Notes | | 속성 | 타입 | 기본값 | 비고 |
|---|---|---|---| |---|---|---|---|
| `name` | string | — | Required, unique, and distinct from every other name once normalised for the environment | | `name` | string | — | 필수. 유일하고, 환경 변수용으로 정규화한 뒤에도 다른 모든 이름과 달라야 한다 |
| `mode` | `TRUSTED` \| `DYNAMIC` | `TRUSTED` | A dynamic profile may not carry a default credential | | `mode` | `TRUSTED` \| `DYNAMIC` | `TRUSTED` | dynamic profile은 기본 credential을 가질 수 없다 |
| `base-url` | URI | — | Required for a trusted profile; no userinfo, no query | | `base-url` | URI | — | trusted profile에 필수. userinfo와 query가 없어야 한다 |
| `allowed-hosts` | list | empty | Required in production | | `allowed-hosts` | list | 비어 있음 | 운영에서 필수 |
| `allowed-ports` | list | empty | Compared against the effective port | | `allowed-ports` | list | 비어 있음 | 실제 port와 비교한다 |
| `transport` | `APACHE` \| `JDK` \| `JETTY` \| `SIMPLE` | `APACHE` | `SIMPLE` is rejected in production; `JETTY` needs a deployment-registered provider | | `transport` | `APACHE` \| `JDK` \| `JETTY` \| `SIMPLE` | `APACHE` | `SIMPLE`은 운영에서 거부한다. `JETTY`는 배포가 등록한 provider가 필요하다 |
| `protocols` | list | `HTTP_1_1` | The default transport is Apache, whose classic client is HTTP/1.1 only; a profile that wants HTTP/2 declares it together with a transport that can deliver it. `HTTP_3` requires the experimental acknowledgement | | `protocols` | list | `HTTP_1_1` | 기본 transport는 Apache이고, 그 classic client는 HTTP/1.1만 한다. HTTP/2를 원하는 profile은 그것을 줄 수 있는 transport와 함께 선언한다. `HTTP_3`은 실험 동의가 필요하다 |
| `experimental-acknowledgement` | string | — | Must equal `I_ACCEPT_HTTP3_EXPERIMENTAL_SEMANTICS` | | `experimental-acknowledgement` | string | — | `I_ACCEPT_HTTP3_EXPERIMENTAL_SEMANTICS`와 같아야 한다 |
### `pool` ### `pool`
| Property | Default | Meaning | | 속성 | 기본값 | 뜻 |
|---|---|---| |---|---|---|
| `max-total-connections` | `50` | Socket ceiling for the runtime | | `max-total-connections` | `50` | 런타임의 socket 상한 |
| `max-connections-per-route` | `25` | Per-upstream ceiling | | `max-connections-per-route` | `25` | upstream 하나의 상한 |
| `max-pending-acquires` | `100` | Waiting-request memory ceiling | | `max-pending-acquires` | `100` | 기다리는 요청의 메모리 상한 |
| `pending-acquire-timeout` | `200ms` | Pool or stream wait ceiling | | `pending-acquire-timeout` | `200ms` | pool이나 stream을 기다리는 상한 |
| `max-idle-time` | `30s` | Idle eviction | | `max-idle-time` | `30s` | 놀고 있는 connection 내보내기 |
| `max-life-time` | `5m` | Picks up DNS, load-balancer, and certificate changes | | `max-life-time` | `5m` | DNS, load balancer, 인증서 변화를 받아들인다 |
| `validate-after-inactivity` | `5s` | Stale and half-open detection | | `validate-after-inactivity` | `5s` | 낡거나 반쯤 열린 connection 감지 |
| `requires-route-pool` | `false` | Set when route-scoped limits are mandatory; the JDK transport then refuses the profile | | `requires-route-pool` | `false` | route 범위 상한이 필수일 때 켠다. 그러면 JDK transport가 그 profile을 거부한다 |
| `requires-bounded-pending-queue` | `false` | Same, for a bounded pending queue | | `requires-bounded-pending-queue` | `false` | 같은 방식으로, 상한 있는 대기 큐가 필수일 때 |
### `timeout` ### `timeout`
| Property | Default | Meaning | | 속성 | 기본값 | 뜻 |
|---|---|---| |---|---|---|
| `dns` | `300ms` | Hostname resolution | | `dns` | `300ms` | hostname 풀기 |
| `connect` | `500ms` | Socket connect | | `connect` | `500ms` | socket 연결 |
| `tls-handshake` | `1s` | TLS and ALPN | | `tls-handshake` | `1s` | TLS와 ALPN |
| `response-header` | `2s` | Until final response headers | | `response-header` | `2s` | 최종 응답 헤더까지 |
| `read-idle` | `3s` | Between response chunks | | `read-idle` | `3s` | 응답 chunk 사이 |
| `total-call` | `4s` | The whole logical call, including retry backoff | | `total-call` | `4s` | 재시도 backoff를 포함한 논리 호출 전체 |
`total-call` must not be shorter than `connect` or `response-header`; the validator emits `total-call`은 `connect`나 `response-header`보다 짧으면 안 된다. 짧으면 validator가 `INVALID_TIMEOUT_BUDGET`을
`INVALID_TIMEOUT_BUDGET` otherwise. Every timeout above, and `pool.pending-acquire-timeout`, must be 낸다. 위의 모든 timeout과 `pool.pending-acquire-timeout`은 0보다 커야 한다(`TIMEOUT_NOT_POSITIVE`). 두 엔진 모두
greater than zero (`TIMEOUT_NOT_POSITIVE`): both engines read zero as "wait forever". 0을 「영원히 기다림」으로 읽는다.
`total-call` also bounds the setup of a streaming download — connect, send, and the wait for `total-call`은 스트리밍 다운로드의 준비 단계(연결, 보내기, 응답 헤더 기다리기)도 제한한다. stream을 넘긴 뒤에는
response headers. Once the stream is handed over, each gap of the body is bounded by `read-idle` 본문의 틈마다 `read-idle`이 제한한다. 그래서 긴 다운로드가 임의의 총 시간에 잘리지 않는다(설계서 §15.3). 두
instead, so a long download is not cut at an arbitrary total (design §15.3). This holds on both transport 모두 그렇다.
transports. The JDK transport keeps its exchange-wide timeout off a streamed body, and a per-stream
watchdog bounds each read's wait by `read-idle`, because the JDK client has no socket read timeout.
The watchdog wakes on one daemon thread of its own (`httpclient-jdk-read-idle`), not on the common
`ForkJoinPool`, so a service that fills that pool with blocking work does not delay it (re-review
2026-11-04 RR3-03-01). That thread ends 60 s after the last wake it had queued and the next stream
starts it again; it inherits no thread-locals from the request thread that starts it and uses the
module's class loader as its context loader, so an idle service keeps no thread and a redeployed
application's loader is not pinned (RR4-03-04). Before review 2026-11-03 RR-04-03 every JDK download longer than
`response-header` was cut mid-body. A body failure after hand-over is thrown from `read` as `HttpBodyReadException` — an `IOException`, as
`InputStream` promises, so `catch (IOException)` still sees it — whose `failure()` is
`HttpResponseTimeoutException` (a wait longer than `read-idle`) or `HttpResponseTruncatedException`
(the connection ended early), stage `RESPONSE_BODY`, evidence `PARTIAL_RESPONSE` (re-review
2026-11-04 RR-03-14). On the JDK transport `read-idle` bounds each read's wait, `skip` included, and
time the caller spends between reads does not count (RR-03-12).
### Removed settings - JDK transport는 스트리밍 본문에 exchange 전체 timeout을 걸지 않는다. JDK client에는 socket 읽기 timeout이
없으므로 stream마다 watchdog이 읽기 대기를 `read-idle`로 제한한다.
- watchdog은 공용 `ForkJoinPool`이 아니라 자기 daemon 스레드 하나(`httpclient-jdk-read-idle`)에서 깬다. 그래서
그 pool을 blocking 작업으로 채운 서비스도 watchdog을 늦추지 않는다(재리뷰 2026-11-04 RR3-03-01).
- 그 스레드는 마지막으로 예약한 깨우기 60초 뒤에 끝나고, 다음 stream이 다시 띄운다. 띄운 요청 스레드의
thread-local을 물려받지 않고, 모듈의 class loader를 context loader로 쓴다. 그래서 노는 서비스는 스레드를
붙들지 않고, 다시 배포한 애플리케이션의 loader가 붙잡히지 않는다(RR4-03-04).
- 리뷰 2026-11-03 RR-04-03 전에는 `response-header`보다 긴 JDK 다운로드가 모두 본문 중간에 잘렸다.
Six keys were removed because they were bound and reached no transport (review 2026-11-01 05-15). 넘긴 뒤의 본문 실패는 `read`에서 `HttpBodyReadException`으로 던진다. `InputStream`이 약속한 대로 `IOException`
Setting one now fails startup with a bind error naming the key (`The elements 이므로 `catch (IOException)`도 그것을 잡는다. 그 `failure()`는 `HttpResponseTimeoutException`(`read-idle`보다 긴
[app.httpclient.clients[0].timeout.request-write-idle] were left unbound.`), instead of being 기다림)이나 `HttpResponseTruncatedException`(connection이 일찍 끝남)이고, 단계는 `RESPONSE_BODY`, 증거는
accepted and ignored. `PARTIAL_RESPONSE`다(재리뷰 2026-11-04 RR-03-14). JDK transport에서 `read-idle`은 `skip`을 포함해 읽기마다의
기다림을 제한하고, 호출자가 읽기 사이에 쓴 시간은 세지 않는다(RR-03-12).
| Removed key | Why | ### 지운 설정
어느 transport에도 닿지 않으면서 바인딩만 되던 key 여섯을 지웠다(리뷰 2026-11-01 05-15). 이제 그 key를 쓰면
받아들이고 무시하는 대신 그 key를 이름 댄 바인딩 오류(`The elements
[app.httpclient.clients[0].timeout.request-write-idle] were left unbound.`)로 시작이 실패한다.
| 지운 key | 이유 |
|---|---| |---|---|
| `timeout.request-write-idle` | Neither engine can bound a blocking socket write | | `timeout.request-write-idle` | 어느 엔진도 blocking socket 쓰기를 제한하지 못한다 |
| `timeout.proxy-connect`, `proxy.connect-timeout` | The TCP connect to a proxy is governed by `timeout.connect` | | `timeout.proxy-connect`, `proxy.connect-timeout` | proxy로의 TCP 연결은 `timeout.connect`가 정한다 |
| `pool.eviction-interval` | Apache's idle evictor runs at `max-idle-time` | | `pool.eviction-interval` | Apache의 idle evictor는 `max-idle-time`마다 돈다 |
| `pool.shutdown-timeout` | A retired runtime drains for `app.httpclient.rotation-drain-timeout` | | `pool.shutdown-timeout` | 내린 런타임은 `app.httpclient.rotation-drain-timeout` 동안 비운다 |
| `observability.operation-name-required` | An operation name is mandatory in the API; the switch could only be true | | `observability.operation-name-required` | 연산 이름은 API에서 필수다. 이 스위치는 true일 수밖에 없었다 |
### `circuit-breaker` ### `circuit-breaker`
What counts as a failure is fixed: a 5xx, 408 or 429 response — whether the call throws or returns 무엇을 실패로 세는지는 고정이다. 5xx, 408, 429 응답(호출이 던지든 결과로 돌려주든)과 모든 transport 실패다.
it as a result — and every transport failure. Every other 4xx is a healthy answer. These settings 그 밖의 4xx는 건강한 답이다. 이 설정은 몇 번 중 몇 번의 실패가 circuit을 여는지만 정한다. 기본값은
only say how many failures, out of how many calls, open the circuit. Defaults are Resilience4j's own, Resilience4j 자체의 값이고, key가 생기기 전 모든 profile이 이 값으로 돌았다.
which every profile ran with before the keys existed.
Two deadlines can end an attempt in flight, and they are counted differently (review 2026-11-03 진행 중인 시도를 끝낼 수 있는 기한은 둘이고, 둘을 다르게 센다(리뷰 2026-11-03 RR-04-01).
RR-04-01):
| Ended by | Breaker | Why | | 끝낸 것 | Breaker | 이유 |
|---|---|---| |---|---|---|
| The caller's own deadline (`HttpOperation.deadline()`, when earlier than `total-call`) | Not recorded; the permission is given back | The caller ran out of time. Counting it opened the circuit on a healthy upstream whenever callers passed short budgets | | 호출자 자신의 기한(`HttpOperation.deadline()`, `total-call`보다 이를 때) | 기록하지 않고 허가를 돌려준다 | 호출자의 시간이 다 됐을 뿐이다. 이것을 세면 호출자가 짧은 예산을 줄 때마다 건강한 upstream의 circuit이 열렸다 |
| The profile's `timeout.total-call` | Recorded as a failure | `total-call` is the operator's statement of how long a healthy upstream may take; a slow-drip upstream that never trips a per-gap timeout is seen only through it | | profile의 `timeout.total-call` | 실패로 기록한다 | `total-call`은 건강한 upstream이 걸려도 되는 시간에 대한 운영자의 말이다. 틈마다의 timeout에 걸리지 않고 조금씩 흘리는 upstream은 이것으로만 보인다 |
The first row has a blind spot (re-review 2026-11-04 RR-03-16). The attempt is let off whenever the 첫 행에는 사각지대가 있다(재리뷰 2026-11-04 RR-03-16). 호출자의 기한이 더 이르고, 시도가 실패했을 때 그 기한이
caller's deadline was the earlier one and had passed when the attempt failed — the code does not ask 지났으면 그 시도는 세지 않는다. 코드는 upstream이 그때도 profile 한도 안에서 답하고 있었는지 묻지 않는다.
whether the upstream was still answering within the profile's limits. If every caller of a profile 어떤 profile의 모든 호출자가 `connect`나 `response-header`보다 짧은 예산을 주면, 멈춘 upstream(패킷을 버리거나
passes a budget shorter than `connect` or `response-header`, an upstream that hangs (drops packets, 답하지 않음)은 모든 시도를 호출자의 기한에서 먼저 끝낸다. 그래서 아무 시도도 기록되지 않고 circuit은 열리지
never answers) ends every attempt at the caller's deadline first, so no attempt is recorded and the 않으며, 모든 호출이 자기 예산을 다 기다린다. 호출자의 기한 전에 오는 실패(거부된 연결)는 여전히 센다. 그런
circuit never opens; every call waits out its own budget. A failure that comes before the caller's profile에는 `connect`와 `response-header`를 가장 짧은 호출자 예산보다 짧게 둔다.
deadline — a refused connection — is still counted. For such a profile, set `connect` and
`response-header` shorter than the shortest caller budget.
| Property | Default | Meaning | | 속성 | 기본값 | 뜻 |
|---|---|---| |---|---|---|
| `failure-rate-threshold` | `50` | Percent of failed calls in the window that opens the circuit, 1–100 | | `failure-rate-threshold` | `50` | circuit을 여는, 창 안 실패 호출의 백분율. 1–100 |
| `minimum-number-of-calls` | `100` | Calls recorded before the rate is evaluated; at most `sliding-window-size` | | `minimum-number-of-calls` | `100` | 비율을 계산하기 전에 기록할 호출 수. `sliding-window-size` 이하 |
| `sliding-window-size` | `100` | The last N calls the rate is computed over (count-based) | | `sliding-window-size` | `100` | 비율을 계산하는 최근 N개 호출(개수 기준) |
| `wait-duration-in-open-state` | `60s` | How long an open circuit rejects before trial calls; positive | | `wait-duration-in-open-state` | `60s` | 열린 circuit이 시험 호출 전까지 거부하는 시간. 양수 |
| `permitted-calls-in-half-open-state` | `10` | Trial calls while half-open; at least 1 | | `permitted-calls-in-half-open-state` | `10` | half-open 동안의 시험 호출. 1 이상 |
An out-of-range value fails startup with `CIRCUIT_BREAKER_SETTING_INVALID`. The breaker belongs to 범위 밖 값은 `CIRCUIT_BREAKER_SETTING_INVALID`로 시작이 실패한다. breaker는 런타임 세대가 아니라 profile에
the profile, not to a runtime generation, so a certificate rotation keeps its state. 속한다. 그래서 인증서를 교체해도 상태가 남는다.
### `redirect`, `request`, `response` ### `redirect`, `request`, `response`
| Property | Default | Meaning | | 속성 | 기본값 | 뜻 |
|---|---|---| |---|---|---|
| `redirect.enabled` | `false` | Engine redirect handling is always off; the platform follows hops itself | | `redirect.enabled` | `false` | 엔진의 redirect 처리는 늘 꺼져 있다. 플랫폼이 hop을 직접 따라간다 |
| `redirect.max-hops` | `0` | Enabling redirects with zero hops is a configuration error | | `redirect.max-hops` | `0` | redirect를 켜고 hop을 0으로 두면 설정 오류다 |
| `redirect.allow-cross-origin` | `false` | When enabled, credentials are stripped on the hop | | `redirect.allow-cross-origin` | `false` | 켜면 hop에서 credential을 지운다 |
| `request.max-body-bytes` | `0` | Required in production | | `request.max-body-bytes` | `0` | 운영에서 필수 |
| `request.compression` | `false` | | | `request.compression` | `false` | |
| `response.max-wire-bytes` | `5242880` | Bytes on the wire | | `response.max-wire-bytes` | `5242880` | wire 위의 바이트 |
| `response.max-decoded-bytes` | `10485760` | Bytes after decoding; hard maximum is 64 MiB | | `response.max-decoded-bytes` | `10485760` | 디코딩한 뒤의 바이트. 넘을 수 없는 최대는 64 MiB |
| `response.allowed-content-types` | JSON + problem+json | Empty means "any" | | `response.allowed-content-types` | JSON + problem+json | 비어 있으면 「아무것이나」 |
### `authentication` ### `authentication`
| Property | Default | Meaning | | 속성 | 기본값 | 뜻 |
|---|---|---| |---|---|---|
| `type` | `NONE` | One of the design §20.1 methods | | `type` | `NONE` | 설계서 §20.1의 방식 중 하나 |
| `registration-id` | — | Required for OAuth2 | | `registration-id` | — | OAuth2에 필수 |
| `scopes` | empty | Part of the token cache key | | `scopes` | 비어 있음 | token cache key의 일부 |
| `audience` | — | Part of the token cache key | | `audience` | — | token cache key의 일부 |
| `header-name` | — | Required for `API_KEY_HEADER`; must be on the allowlist | | `header-name` | — | `API_KEY_HEADER`에 필수. 허용 목록에 있어야 한다 |
| `secret-reference` | — | Resolved by the deployment's secret loader, never a literal | | `secret-reference` | — | 배포의 secret loader가 푼다. 값을 그대로 쓰지 않는다 |
### `retry` ### `retry`
| Property | Default | Meaning | | 속성 | 기본값 | 뜻 |
|---|---|---| |---|---|---|
| `policy` | `none` | Named policy for reporting | | `policy` | `none` | 보고용 정책 이름 |
| `max-attempts` | `1` | Attempts, not retries; at most 5 (`RETRY_MAX_ATTEMPTS_EXCEEDED`) | | `max-attempts` | `1` | 재시도 수가 아니라 시도 수. 최대 5(`RETRY_MAX_ATTEMPTS_EXCEEDED`) |
| `base-backoff` | `50ms` | | | `base-backoff` | `50ms` | |
| `max-backoff` | `200ms` | | | `max-backoff` | `200ms` | |
| `jitter` | `FULL` | `NONE` \| `FULL` \| `DECORRELATED` | | `jitter` | `FULL` | `NONE` \| `FULL` \| `DECORRELATED` |
| `retry-after` | `HONOR` | `HONOR` \| `IGNORE` \| `CAP` | | `retry-after` | `HONOR` | `HONOR` \| `IGNORE` \| `CAP` |
| `budget` | — | Shared token bucket name. A retrying profile that names none gets its own bucket, with the same pool-derived capacity (`max-total-connections / 10`, at least 1, refilled each minute) | | `budget` | — | 공유 token bucket 이름. 재시도하는 profile이 이름을 주지 않으면 자기 bucket을 받는다. 용량 계산은 같다(`max-total-connections / 10`, 최소 1, 1분마다 채움) |
### `tls` ### `tls`
| Property | Default | Meaning | | 속성 | 기본값 | 뜻 |
|---|---|---| |---|---|---|
| `profile-id` | — | Required in production; the only TLS identifier the actuator exposes | | `profile-id` | — | 운영에서 필수. actuator가 보여 주는 유일한 TLS 식별자 |
| `protocols` | `TLSv1.3, TLSv1.2` | Anything else is rejected | | `protocols` | `TLSv1.3, TLSv1.2` | 그 밖의 값은 거부한다 |
| `hostname-verification` | `true` | Setting it false fails startup | | `hostname-verification` | `true` | false로 두면 시작이 실패한다 |
| `trust-all` | `false` | Exists only so the unsafe intent is rejectable; nothing acts on `true` | | `trust-all` | `false` | 위험한 의도를 거부할 수 있게 하려고만 있다. `true`에 반응하는 것은 없다 |
| `allow-plain-http` | `false` | Plaintext fallback fails startup in production | | `allow-plain-http` | `false` | 평문으로 물러서기는 운영에서 시작을 실패시킨다 |
| `trust-material-reference` | — | Custom CA, resolved by the secret loader | | `trust-material-reference` | — | 사설 CA. secret loader가 푼다 |
| `key-material-reference` | — | Client certificate for mTLS | | `key-material-reference` | — | mTLS용 client 인증서 |
### `proxy` and `observability` ### `proxy`와 `observability`
| Property | Default | Meaning | | 속성 | 기본값 | 뜻 |
|---|---|---| |---|---|---|
| `proxy.enabled` | `false` | | | `proxy.enabled` | `false` | |
| `proxy.host` / `proxy.port` / `proxy.type` | — / `0` / `HTTP` | | | `proxy.host` / `proxy.port` / `proxy.type` | — / `0` / `HTTP` | |
| `proxy.credential-provider` | — | Proxy authentication is separate from target authentication | | `proxy.credential-provider` | — | proxy 인증은 대상 인증과 따로다 |
| `proxy.import-ambient-no-proxy` | `false` | Ambient `NO_PROXY` never widens a validated profile | | `proxy.import-ambient-no-proxy` | `false` | 환경의 `NO_PROXY`는 검증한 profile을 넓히지 않는다 |
| `observability.full-url-recording` | `false` | | | `observability.full-url-recording` | `false` | |
| `observability.body-logging` | `false` | | | `observability.body-logging` | `false` | |
## `app.httpclient.dynamic-targets[N]` ## `app.httpclient.dynamic-targets[N]`
| Property | Default | Meaning | | 속성 | 기본값 | 뜻 |
|---|---|---| |---|---|---|
| `name` | — | Required, unique, and subject to the same normalisation rule as a client name | | `name` | — | 필수, 유일, client 이름과 같은 정규화 규칙 |
| `allowed-schemes` | `https` | | | `allowed-schemes` | `https` | |
| `allowed-ports` | `443` | | | `allowed-ports` | `443` | |
| `allowed-host-suffixes` | empty | | | `allowed-host-suffixes` | 비어 있음 | |
| `allowed-hosts` | empty | Empty means "any host that survives address validation" | | `allowed-hosts` | 비어 있음 | 비어 있으면 「주소 검증을 통과한 아무 host」 |
| `max-redirect-hops` | `0` | Each hop repeats the full validation flow | | `max-redirect-hops` | `0` | hop마다 검증 흐름 전체를 다시 돈다 |
| `trace-propagation` | `false` | Off by default for dynamic targets | | `trace-propagation` | `false` | dynamic target은 기본으로 끈다 |
| `blocked-cidrs` | empty | Organisation-defined internal ranges | | `blocked-cidrs` | 비어 있음 | 조직이 정한 내부 범위 |
## Startup violation codes ## 시작 위반 코드
`TRUSTED_BASE_URL_REQUIRED`, `BASE_URL_USERINFO_FORBIDDEN`, `BASE_URL_QUERY_FORBIDDEN`, `TRUSTED_BASE_URL_REQUIRED`, `BASE_URL_USERINFO_FORBIDDEN`, `BASE_URL_QUERY_FORBIDDEN`,
`PLAINTEXT_PRODUCTION_TARGET`, `ALLOWED_HOST_MISMATCH`, `ALLOWED_PORT_MISMATCH`, `PLAINTEXT_PRODUCTION_TARGET`, `ALLOWED_HOST_MISMATCH`, `ALLOWED_PORT_MISMATCH`,
@@ -259,36 +250,33 @@ the profile, not to a runtime generation, so a certificate rotation keeps its st
`DNS_TIMEOUT_UNSUPPORTED`, `PROXY_CREDENTIAL_UNSUPPORTED`, `PROXY_AMBIENT_NO_PROXY_UNSUPPORTED`, `DNS_TIMEOUT_UNSUPPORTED`, `PROXY_CREDENTIAL_UNSUPPORTED`, `PROXY_AMBIENT_NO_PROXY_UNSUPPORTED`,
`TIMEOUT_NOT_POSITIVE`, `RETRY_MAX_ATTEMPTS_EXCEEDED`, `CIRCUIT_BREAKER_SETTING_INVALID`. `TIMEOUT_NOT_POSITIVE`, `RETRY_MAX_ATTEMPTS_EXCEEDED`, `CIRCUIT_BREAKER_SETTING_INVALID`.
A key that names no setting is not a violation code: the shared strict binder 어떤 설정도 가리키지 않는 key는 위반 코드가 아니다. 공용 엄격 binder(`adapter:outbound:support`
(`adapter:outbound:support` `StrictSettingsBinder`) refuses it while binding, at any depth. Spring's `StrictSettingsBinder`)가 바인딩하면서 깊이와 상관없이 거부한다. Spring 자체의 바인딩 안 된 key 검사는 list 원소
own unbound-key check stops at the first level under a list element, so `clients[0].timeout.<typo>` 아래 첫 단계에서 멈춘다. 그래서 `clients[0].timeout.<typo>`는 아무것도 바인딩하지 않고 아무것도 실패시키지
used to bind nothing and fail nothing; the binder now refuses a key under `clients[N]` or 않았다. 이제 binder는 `clients[N]`이나 `dynamic-targets[N]` 아래에서 아무것도 바인딩하지 않은 key를 이
`dynamic-targets[N]` that bound nothing, for every capability rather than for this platform alone 플랫폼만이 아니라 모든 capability에서 거부한다(리뷰 2026-11-01 05-15). 그 변경과 함께 플랫폼 자체의 보호 장치와
(review 2026-11-01 05-15). The platform's own guard for it, and its `HTTPCLIENT_UNKNOWN_SETTING` 그 `HTTPCLIENT_UNKNOWN_SETTING` 코드는 지웠다.
code, were removed with that change.
`DNS_TIMEOUT_UNSUPPORTED`, `PROXY_CREDENTIAL_UNSUPPORTED` and `PROXY_AMBIENT_NO_PROXY_UNSUPPORTED` name settings the platform binds but cannot yet honour. Neither the Apache classic `DNS_TIMEOUT_UNSUPPORTED`, `PROXY_CREDENTIAL_UNSUPPORTED`, `PROXY_AMBIENT_NO_PROXY_UNSUPPORTED`는 플랫폼이
client nor the JDK client exposes a DNS-resolution timeout, and no proxy-credential path exists, so 바인딩은 하지만 아직 지키지 못하는 설정을 가리킨다. Apache classic client도 JDK client도 DNS 풀기 timeout을
a non-default value is refused rather than accepted and ignored. Leaving the defaults alone is 내놓지 않고, proxy credential 경로도 없다. 그래서 기본값이 아닌 값은 받아들이고 무시하지 않고 거부한다.
unaffected — only a deliberate, unmet request fails. 기본값을 그대로 두면 영향이 없다. 의도했지만 지킬 수 없는 요청만 실패한다.
Three of these are about a guarantee that used to be silently unmet rather than refused: 아래 코드들은 예전에 거부하지 않고 조용히 지키지 못하던 보장에 관한 것이다.
- `HTTP2_REQUIRED_TRANSPORT_UNSUPPORTED` — declaring `protocols: [HTTP_2]` alone states that HTTP/2 - `HTTP2_REQUIRED_TRANSPORT_UNSUPPORTED` — `protocols: [HTTP_2]`만 선언하면 HTTP/2가 필수라는 뜻이다. H2만
is required. No transport can be configured to offer H2 and nothing else; the JDK client treats it 제공하도록 설정할 수 있는 transport는 없다. JDK client는 그것을 선호로 다루고 HTTP/1.1로 협상하고, Apache의
as a preference and negotiates HTTP/1.1, and Apache's classic client is HTTP/1.1 only. classic client는 HTTP/1.1만 한다.
- `POOL_ROUTE_EXCEEDS_TOTAL` — a per-route ceiling above the total is incoherent. - `POOL_ROUTE_EXCEEDS_TOTAL` — route별 상한이 전체보다 크면 앞뒤가 맞지 않는다.
- `TLS_PROTOCOL_SET_REQUIRED` — an empty `tls.protocols` used to pass and then let the JVM choose, - `TLS_PROTOCOL_SET_REQUIRED` — 빈 `tls.protocols`가 예전에는 통과해서 JVM이 고르게 두었다. 그래서 profile을
so emptying the list to "tighten" a profile loosened it. 「조이려고」 목록을 비우면 오히려 풀렸다.
- `RETRY_POLICY_CONTRADICTS_ATTEMPTS` — `retry.policy` was read by nothing on the execution path, so - `RETRY_POLICY_CONTRADICTS_ATTEMPTS` — 실행 경로의 어느 것도 `retry.policy`를 읽지 않았다. 그래서 세 번
the actuator could report `none` for a profile retrying three times. The two settings must now 재시도하는 profile에 대해 actuator가 `none`을 보고할 수 있었다. 이제 두 설정이 맞아야 한다. `policy: none`은
agree: `policy: none` requires `max-attempts: 1`, and any other policy requires more than one. `max-attempts: 1`을 요구하고, 다른 정책은 1보다 큰 값을 요구한다.
- `FULL_URL_RECORDING_FORBIDDEN` / `BODY_LOGGING_FORBIDDEN` — both settings were bindable and inert. - `FULL_URL_RECORDING_FORBIDDEN` / `BODY_LOGGING_FORBIDDEN` — 두 설정은 바인딩은 됐지만 아무 효과가 없었다.
Recording an expanded URL puts path identifiers and query strings into unbounded metric tags; 펼친 URL을 기록하면 경로 식별자와 query string이 상한 없는 metric tag에 들어가고, 본문을 기록하면 남의 데이터가
recording bodies puts someone else's data into logs. Representable so the intent is rejectable, 로그에 들어간다. 의도를 거부할 수 있게 표현만 해 두고, 운영 profile에서는 거부한다.
refused under a production profile.
`DYNAMIC_TARGET_PROXY_UNSUPPORTED` is worth spelling out: a forward proxy resolves the hostname on `DYNAMIC_TARGET_PROXY_UNSUPPORTED`는 따로 설명할 만하다. forward proxy는 hostname을 자기 쪽에서 푼다. 그래서
its own side, so the addresses this platform validated and pinned are not the addresses the 이 플랫폼이 검증하고 고정한 주소가 연결이 실제로 닿는 주소가 아니다. SSRF 방어는 있고 맞지만 우회된다. 그래서
connection reaches. The SSRF defence would be present, correct, and bypassed — so the combination is 이 조합은 지킬 수 없는 보장을 단 채 내주지 않고 거부한다.
refused rather than served with a guarantee it cannot keep.
+19 -21
View File
@@ -1,29 +1,27 @@
# HTTP Client platform — Java field path to environment variable template. # HTTP Client 플랫폼 — Java 필드 경로에서 환경 변수 template로의 대응.
# #
# The SSOT is HttpClientPlatformSettings. HttpClientPlatformEnvManifestTest derives this list from # 정본은 HttpClientPlatformSettings다. HttpClientPlatformEnvManifestTest가 record 트리에서 이 목록을 만들어
# the record tree and fails when the two disagree in either direction, and the shared strict binder # 양쪽 방향으로 어긋나면 실패하고, 공용 엄격 binder는 어떤 필드도 가리키지 않는 APP_HTTPCLIENT_ 변수가
# refuses to start on an APP_HTTPCLIENT_ variable that names no field. So a # 있으면 시작을 거부한다. 그래서 항목 없이 더한 필드, 필드 이름이 바뀐 항목, 배포의 오타 변수가 모두
# field added with no entry, an entry whose field was renamed, and a misspelled variable in a # 조용히 넘어가지 않고 실패한다.
# deployment are all failures rather than silence.
# #
# `N` and `M` are list indices, not literals: `N` for the outermost list, `M` for a list inside it. # `N`과 `M`은 글자 그대로가 아니라 list index다. `N`은 바깥 list, `M`은 그 안의 list다.
# `app.httpclient.clients[N].base-url` is set as APP_HTTPCLIENT_CLIENTS_0_BASE_URL for the first # 첫 client의 `app.httpclient.clients[N].base-url`은 APP_HTTPCLIENT_CLIENTS_0_BASE_URL로,
# client, and `clients[N].allowed-hosts[M]` as APP_HTTPCLIENT_CLIENTS_0_ALLOWED_HOSTS_0. # `clients[N].allowed-hosts[M]`은 APP_HTTPCLIENT_CLIENTS_0_ALLOWED_HOSTS_0으로 준다.
# #
# Only APP_HTTPCLIENT_ENABLED is registered in docs/registries/env-keys.yaml and shipped in # docs/registries/env-keys.yaml에 등록하고 src/.env에 담는 것은 APP_HTTPCLIENT_ENABLED뿐이다. 배포와
# src/.env: it is the only key with a deployment-independent value, and it is the only one the # 상관없는 값을 가진 유일한 key이고, 세 방향을 대조하는 :app-bootstrap:verifyEnvKeys 게이트가 표현할 수
# three-way :app-bootstrap:verifyEnvKeys gate can express. Everything below is per deployment and is set directly # 있는 유일한 key다. 아래 나머지는 모두 배포마다 다르고 환경에 직접 준다. index를 단 client를
# in the environment — templating an indexed client in application.yml would materialise a nameless # application.yml에 template로 두면 모든 배포에 이름 없는 client가 생기고, settings의 묶음 검증이 그것을
# client in every deployment, which the settings' aggregate validation refuses. # 거부한다.
# #
# This file lives beside the HTTP Client documentation rather than in docs/registries, which is a # 이 파일은 docs/registries가 아니라 HTTP Client 문서 옆에 있다. docs/registries는 행 schema
# fail-closed catalog of exactly eight contract registries with a fixed row schema # (행마다 owner_branch/compatibility_impact/required_test)가 고정된 계약 registry만 받는, 닫힌 쪽으로
# (owner_branch/compatibility_impact/required_test per row). A field-to-variable mapping does not # 실패하는 목록이다. 필드-변수 대응은 그 모양이 아니고, 받아들이려면 게이트를 맞추는 대신 풀어야 했다.
# have that shape, and admitting it would have meant loosening a gate rather than satisfying one.
# #
# Secrets are referenced, never carried: authentication.secret-reference, tls.*-material-reference # secret은 값이 아니라 참조로 준다. authentication.secret-reference, tls.*-material-reference,
# and proxy.credential-provider name material that a secret backend resolves. Putting the material # proxy.credential-provider는 secret backend가 푸는 재료의 이름이다. 재료 자체를 이 변수에 넣으면
# itself in one of these variables defeats the indirection they exist for. # 이 변수들이 있는 이유인 간접화가 무너진다.
fields: fields:
- field: enabled - field: enabled
env: APP_HTTPCLIENT_ENABLED env: APP_HTTPCLIENT_ENABLED
+91 -97
View File
@@ -1,129 +1,123 @@
# HTTP Client Platform — Operations Runbook # HTTP Client 플랫폼 — 운영 runbook
## Metrics ## Metric
| Metric | Meaning | | Metric | 뜻 |
|---|---| |---|---|
| `http.client.requests` | Physical attempt timer (Spring standard name, kept deliberately) | | `http.client.requests` | 물리 시도 timer(Spring 표준 이름. 일부러 그대로 둔다) |
| `http.client.logical.calls` | User-visible logical call timer | | `http.client.logical.calls` | 사용자에게 보이는 논리 호출 timer |
| `http.client.attempts` | Attempt counter | | `http.client.attempts` | 시도 counter |
| `http.client.retry.count` | Retries by reason | | `http.client.retry.count` | 이유별 재시도 |
| `http.client.retry.exhausted` | Retry budget exhausted | | `http.client.retry.exhausted` | 재시도 예산 소진 |
| `http.client.ambiguous` | Ambiguous outcomes | | `http.client.ambiguous` | 결과를 모르는 경우 |
| `http.client.timeout` | Timeouts by stage | | `http.client.timeout` | 단계별 시간 초과 |
| `http.client.request.bytes` | Request wire bytes | | `http.client.request.bytes` | 요청 wire 바이트 |
| `http.client.response.bytes` | Response bytes | | `http.client.response.bytes` | 응답 바이트 |
| `http.client.active` | In-flight attempts | | `http.client.active` | 진행 중인 시도 |
| `http.client.pool.connections` | Leased and available connections | | `http.client.pool.connections` | 빌려 간 connection과 남은 connection |
| `http.client.pool.pending` | Pool waiters | | `http.client.pool.pending` | pool 대기자 |
| `http.client.pool.acquire.duration` | Pool wait time | | `http.client.pool.acquire.duration` | pool 대기 시간 |
| `http.client.dns.duration` | DNS time | | `http.client.dns.duration` | DNS 시간 |
| `http.client.connect.duration` | Connect time | | `http.client.connect.duration` | 연결 시간 |
| `http.client.tls.duration` | TLS time | | `http.client.tls.duration` | TLS 시간 |
| `http.client.circuit.state` | Circuit state | | `http.client.circuit.state` | circuit 상태 |
| `http.client.bulkhead.rejected` | Bulkhead rejections | | `http.client.bulkhead.rejected` | bulkhead 거부 |
| `http.client.rate_limit.rejected` | Local rate-limit rejections | | `http.client.rate_limit.rejected` | 로컬 속도 제한 거부 |
| `http.client.oauth.refresh` | Token refresh outcomes | | `http.client.oauth.refresh` | token 갱신 결과 |
| `http.client.ssrf.rejected` | Dynamic target rejections | | `http.client.ssrf.rejected` | dynamic target 거부 |
`http.client.requests` counts attempts and `http.client.logical.calls` counts user calls. When they `http.client.requests`는 시도를 세고 `http.client.logical.calls`는 사용자 호출을 센다. 둘이 벌어지면 재시도가
diverge, retries are absorbing failures — which is the first thing to look at during an incident. 실패를 흡수하고 있다는 뜻이다. 장애 때 가장 먼저 볼 곳이다.
## Reading an incident ## 장애 읽기
| Symptom | Likely cause | Where to look | | 증상 | 그럴듯한 원인 | 볼 곳 |
|---|---|---| |---|---|---|
| logical calls fine, attempts spiking | upstream degraded, retries absorbing it | `http.client.retry.count` by reason | | 논리 호출은 괜찮은데 시도가 치솟는다 | upstream이 나빠졌고 재시도가 흡수하고 있다 | 이유별 `http.client.retry.count` |
| `http.client.ambiguous` non-zero | non-idempotent writes reaching `SENT_NO_RESPONSE` | reconcile with the upstream; consider an idempotency key | | `http.client.ambiguous`가 0이 아니다 | 멱등이 아닌 쓰기가 `SENT_NO_RESPONSE`에 닿는다 | upstream과 맞춰 본다. 멱등 key를 검토한다 |
| pool pending climbing | pool too small or upstream slow | `http.client.pool.acquire.duration`, `pool.connections` | | pool 대기가 오른다 | pool이 작거나 upstream이 느리다 | `http.client.pool.acquire.duration`, `pool.connections` |
| circuit open | sustained upstream failure: transport errors, 5xx, 408, 429 | `http.client.circuit.state`; local rejections and other 4xx do not open it | | circuit이 열렸다 | 계속된 upstream 실패: transport 오류, 5xx, 408, 429 | `http.client.circuit.state`. 로컬 거부와 그 밖의 4xx는 circuit을 열지 않는다 |
| `http.client.ssrf.rejected` non-zero | a caller is submitting internal URLs | Dynamic Target policy and audit trail | | `http.client.ssrf.rejected`가 0이 아니다 | 호출자가 내부 URL을 넣고 있다 | Dynamic Target 정책과 감사 기록 |
## Actuator ## Actuator
`GET /actuator/httpclients` reports profile name, runtime generation, state, transport, API, `GET /actuator/httpclients`는 profile 이름, 런타임 세대, 상태, transport, API, protocol, 진행 중인 lease, pool
protocols, active leases, pool ceiling, credential type, TLS profile id, redirect flag, retry policy, 상한, credential 유형, TLS profile id, redirect flag, 재시도 정책, capability 경고를 보고한다. Base URL, credential,
and capability warnings. Base URL, credentials, trust store paths, and resolved IPs are deliberately trust store 경로, 푼 IP는 일부러 뺐다. actuator endpoint에는 secret 저장소보다 많은 사람이 닿는다.
absent: an actuator endpoint is reachable by more people than a secret store is.
## Rotation ## 교체
Certificates and secrets rotate by building a new runtime generation and swapping the registry 인증서와 secret은 살아 있는 client를 바꾸지 않고, 새 런타임 세대를 만들어 registry pointer를 바꿔 끼우는 식으로
pointer, never by mutating a live client. A connection pool holds sockets established under the 교체한다. connection pool은 앞 신원으로 맺은 socket을 쥐고 있다. 그래서 pool은 그대로 두고 재료만 바꾸면, 없어져야
previous identity, so replacing material without replacing the pool leaves live connections 할 인증서로 인증한 connection이 살아 있다.
authenticated by a certificate that is meant to be gone.
```text ```text
build new generation → validate → atomic swap → new calls use it 새 세대 만들기 → 검증 → 원자적 교체 → 새 호출이 그것을 쓴다
old generation → DRAINING → in-flight calls finish → no new retries → forced close at the drain deadline 옛 세대 → DRAINING → 진행 중인 호출이 끝난다 → 새 재시도 없음 → drain 기한에 강제로 닫는다
``` ```
## Shutdown ## 종료
```text ```text
RUNNING → DRAINING RUNNING → DRAINING
new logical calls refused or routed to the new generation 새 논리 호출을 거부하거나 새 세대로 보낸다
in-flight attempts complete 진행 중인 시도가 끝난다
new retries refused 새 재시도를 거부한다
shutdown timeout 종료 시간 초과
remaining calls cancelled 남은 호출을 취소한다
pool closed pool을 닫는다
``` ```
## Retry ownership ## 재시도 소유
Exactly one of the application client, an external SDK, or the service mesh may own retries. 애플리케이션 client, 외부 SDK, service mesh 중 정확히 하나만 재시도를 가진다. 소유자가 둘이면 장애 중에 트래픽이
Two owners multiply traffic during an incident. Record the owner per upstream and check it whenever 곱절로 는다. upstream마다 소유자를 적고, mesh 재시도 정책이 바뀔 때마다 확인한다.
a mesh retry policy changes.
## Error model ## 오류 모델
Every outbound failure is one of these stable types. The type is derived from the classified failure 모든 외부 호출 실패는 아래 안정된 타입 중 하나다. 타입은 엔진이 마침 던진 것이 아니라 분류한 실패 범주에서
category, not from whatever the engine happened to throw, so it means the same thing on Apache and 정한다. 그래서 Apache와 JDK에서 같은 뜻이다. 모두 `HttpFailureMetadata`를 가진다: client, 연산, method, URI
JDK. Each carries `HttpFailureMetadata`: client, operation, method, URI **template**, **template**, 증거, 재전송 가능성, 단계, 재시도 가능 여부, 시도 번호, 흐른 시간, 남은 기한, 상태, trace id.
evidence, replayability, stage, retryability, attempt, elapsed, remaining deadline, status, trace id 그 밖의 것은 없다.
— and nothing else.
| Exception | Raised when | Retryable | | 예외 | 던지는 때 | 재시도 |
|---|---|---| |---|---|---|
| `HttpConfigurationException` | profile, operation, or capability configuration is invalid | never | | `HttpConfigurationException` | profile, 연산, capability 설정이 잘못됐다 | 안 함 |
| `HttpTargetRejectedException` | target URI, host, port, header, or address policy refused the request | never | | `HttpTargetRejectedException` | 대상 URI, host, port, 헤더, 주소 정책이 요청을 거부했다 | 안 함 |
| `HttpDnsException` | hostname resolution failed or timed out | yes, inside budget | | `HttpDnsException` | hostname 풀기가 실패하거나 시간이 넘었다 | 예산 안에서 함 |
| `HttpPoolAcquireTimeoutException` | no connection or stream within the pending-acquire budget | yes, inside budget | | `HttpPoolAcquireTimeoutException` | 대기 예산 안에 connection이나 stream을 얻지 못했다 | 예산 안에서 함 |
| `HttpConnectException` | socket connect failed | yes, inside budget | | `HttpConnectException` | socket 연결이 실패했다 | 예산 안에서 함 |
| `HttpProxyException` | proxy connect, CONNECT tunnel, or proxy auth failed | yes, inside budget | | `HttpProxyException` | proxy 연결, CONNECT tunnel, proxy 인증이 실패했다 | 예산 안에서 함 |
| `HttpTlsException` | TLS handshake failed | only a transient handshake timeout | | `HttpTlsException` | TLS handshake가 실패했다 | 일시적인 handshake 시간 초과만 |
| `HttpRequestWriteException` | request headers or body could not be fully written | only when safely idempotent | | `HttpRequestWriteException` | 요청 헤더나 본문을 다 쓰지 못했다 | 안전하게 멱등일 때만 |
| `HttpResponseTimeoutException` | final headers or a body chunk did not arrive in time | only when safely idempotent | | `HttpResponseTimeoutException` | 최종 헤더나 본문 chunk가 제때 오지 않았다 | 안전하게 멱등일 때만 |
| `HttpResponseTruncatedException` | the response ended before the body was complete | only when safely idempotent and undelivered | | `HttpResponseTruncatedException` | 본문이 끝나기 전에 응답이 끝났다 | 안전하게 멱등이고 아직 넘기지 않았을 때만 |
| `HttpRemoteErrorException` | non-success status without a problem document | per the status rules | | `HttpRemoteErrorException` | problem document 없는 실패 상태 | 상태 규칙대로 |
| `HttpProblemDetailException` | non-success status with a bounded RFC 9457 document | per the status rules | | `HttpProblemDetailException` | 크기가 제한된 RFC 9457 document가 있는 실패 상태 | 상태 규칙대로 |
| `HttpRedirectRejectedException` | a hop violated hop count, origin, method, or replay policy | never | | `HttpRedirectRejectedException` | hop이 hop 수, origin, method, 재전송 정책을 어겼다 | 안 함 |
| `HttpAuthenticationException` | credential materialization or refresh failed | never | | `HttpAuthenticationException` | credential 만들기나 갱신이 실패했다 | 안 함 |
| `HttpSerializationException` | request encoding or response decoding failed | never | | `HttpSerializationException` | 요청 인코딩이나 응답 디코딩이 실패했다 | 안 함 |
| `HttpResponseTooLargeException` | wire or decoded bytes exceeded the profile limit | never | | `HttpResponseTooLargeException` | wire나 디코딩한 바이트가 profile 한도를 넘었다 | 안 함 |
| `HttpDeadlineExceededException` | the effective deadline was reached | never | | `HttpDeadlineExceededException` | 실제 기한에 닿았다 | 안 함 |
| `HttpCircuitOpenException` | the upstream circuit is open | never | | `HttpCircuitOpenException` | upstream circuit이 열렸다 | 안 함 |
| `HttpBulkheadRejectedException` | no attempt or logical admission permit was available | never | | `HttpBulkheadRejectedException` | 시도나 논리 허가를 얻지 못했다 | 안 함 |
| `HttpRateLimitRejectedException` | the local attempt rate limiter rejected the attempt | never | | `HttpRateLimitRejectedException` | 로컬 시도 속도 제한이 시도를 거부했다 | 안 함 |
| `HttpRetryBudgetExhaustedException` | the per-upstream retry budget refused a further attempt | never | | `HttpRetryBudgetExhaustedException` | upstream별 재시도 예산이 다음 시도를 거부했다 | 안 함 |
| `HttpRuntimeDrainingException` | the profile's runtime was retired (certificate rotation) before a granted retry started | never — a new call runs on the replacement | | `HttpRuntimeDrainingException` | 허락한 재시도가 시작되기 전에 profile 런타임이 내려갔다(인증서 교체) | 안 함 — 새 호출은 바뀐 런타임에서 돈다 |
| `HttpUnknownTransportException` | the engine failed in a way no category above describes; the metadata evidence, not the type, says whether it was sent | never | | `HttpUnknownTransportException` | 위 범주 어느 것도 설명하지 못하는 방식으로 엔진이 실패했다. 보냈는지는 타입이 아니라 metadata의 증거가 말한다 | 안 함 |
| `HttpAmbiguousExecutionException` | a non-idempotent request was sent and the outcome is unknown | never — reconcile instead | | `HttpAmbiguousExecutionException` | 멱등이 아닌 요청을 보냈고 결과를 모른다 | 안 함 — 대신 맞춰 본다 |
A streamed body that fails after hand-over is the one place these arrive wrapped: `read` throws 이 예외들이 감싸져서 오는 곳은 하나다. 넘긴 뒤 실패한 스트리밍 본문이다. `read`가 `HttpBodyReadException`을
`HttpBodyReadException`, an `IOException` as `InputStream` promises, and its `failure()` is the 던진다. `InputStream`이 약속한 대로 `IOException`이고, 그 `failure()`가 위의 `HttpResponseTimeoutException`이나
`HttpResponseTimeoutException` or `HttpResponseTruncatedException` above (re-review 2026-11-04 `HttpResponseTruncatedException`이다(재리뷰 2026-11-04 RR-03-14).
RR-03-14).
## Traces ## Trace
```text ```text
http.client.operation logical internal span http.client.operation 논리 호출의 내부 span
└─ http.client.request attempt 1 CLIENT span └─ http.client.request 시도 1의 CLIENT span
└─ http.client.request attempt 2 CLIENT span └─ http.client.request 시도 2의 CLIENT span
``` ```
W3C Trace Context is propagated with a Baggage allowlist. Dynamic Targets do not propagate trace W3C Trace Context를 Baggage 허용 목록과 함께 전파한다. Dynamic Target은 기본으로 trace context를 전파하지
context by default. Retry reason and evidence are recorded as span events; credentials and remote 않는다. 재시도 이유와 증거는 span event로 기록한다. credential과 원격 오류 본문은 절대 속성으로 기록하지 않는다.
error bodies are never recorded as attributes.
+34 -38
View File
@@ -1,55 +1,51 @@
# HTTP Client Platform — Performance Baseline # HTTP Client 플랫폼 — 성능 기준선
The certification lane asserts **resource bounds**, not throughput targets. Its purpose is to prove 인증 lane은 처리량 목표가 아니라 **자원 상한**을 단언한다. 실패하는 upstream, 큰 본문, 교체가 메모리, connection,
that a failing upstream, a large body, or a rotation cannot consume unbounded memory, connections, 스레드, upstream 트래픽을 끝없이 먹지 못함을 증명하려는 것이다. 여기 있는 어떤 것도 실행 중 적응형 기본값이 되지
threads, or upstream traffic. Nothing here becomes a runtime adaptive default: every bound comes 않는다. 모든 상한은 profile에 명시한 설정에서 온다.
from an explicit profile setting.
## How to run ## 돌리는 법
```bash ```bash
# every bound, structural and machine-dependent # 모든 상한: 구조적 상한과 기계에 따른 상한
./gradlew :adapter:outbound:httpclient:httpClientPerformanceTest --console=plain ./gradlew :adapter:outbound:httpclient:httpClientPerformanceTest --console=plain
# JMH benchmarks: numbers only, never a gate # JMH benchmark: 숫자만 낸다. 게이트가 아니다
./gradlew :adapter:outbound:httpclient:jmh --console=plain ./gradlew :adapter:outbound:httpclient:jmh --console=plain
``` ```
The lane asserts every bound in every run. There is no switch that turns the machine-dependent one lane은 매번 모든 상한을 단언한다. 기계에 따라 다른 상한을 끄는 스위치는 없다. 빌드가
off: the strict-lane convention fails a performance lane before it runs when the build sets `performance.assertions.enabled`에 `true` 아닌 값을 넣으면 strict lane convention이 성능 lane을 돌기 전에 실패시키고,
`performance.assertions.enabled` to anything but `true`, and fails it when one of its tests is 테스트 하나라도 건너뛰면 실패시킨다. `integration-main.yml`(`:performanceCheck`)과 `release.yml`이 도는 것도 같은
skipped. The same command is what `integration-main.yml` (`:performanceCheck`) and `release.yml` 명령이다. 매번 잰 heap 증가량(`[httpclient-performance] streaming download heap increase … bytes, bound … bytes`)을
run. Every run prints the measured heap increase (`[httpclient-performance] streaming download heap 테스트 출력과 보고서에 찍고, 실패한 상한은 단언 메시지에 그 값을 다시 적는다. 판정 없는 숫자가 필요하면 JMH를 쓴다.
increase … bytes, bound … bytes`) to the test output and report, and a bound that fails repeats the
value in its assertion message; for numbers without a verdict, use JMH.
## Certified bounds ## 인증한 상한
| Test | Bound | Kind | | 테스트 | 상한 | 종류 |
|---|---|---| |---|---|---|
| `RetryStormBudgetTest` | 10 000 logical calls against a failing upstream produce at most 11 000 physical attempts at a 10 % budget | structural | | `RetryStormBudgetTest` | 실패하는 upstream에 대한 논리 호출 10 000개가 10 % 예산에서 물리 시도를 최대 11 000개 만든다 | 구조적 |
| `LargeBodyResourceTest` | a 32 MiB streaming download consumes every byte without buffering the payload on the heap | structural + machine-dependent heap bound | | `LargeBodyResourceTest` | 32 MiB 스트리밍 다운로드가 payload를 heap에 버퍼링하지 않고 모든 바이트를 읽는다 | 구조적 + 기계에 따른 heap 상한 |
| `PoolSaturationPerformanceTest` | 24 concurrent calls against a 4-connection pool all reach a terminal outcome; none hang | structural | | `PoolSaturationPerformanceTest` | connection 4개짜리 pool에 대한 동시 호출 24개가 모두 끝 상태에 닿는다. 멈춘 것이 없다 | 구조적 |
| `OAuthRefreshContentionTest` | 100 genuinely concurrent callers produce exactly one token request | structural | | `OAuthRefreshContentionTest` | 정말 동시에 부르는 호출자 100개가 token 요청을 정확히 하나 만든다 | 구조적 |
| `RuntimeRotationDrainTest` | 50 rotations close all 50 retired generations and leave no drain thread | structural | | `RuntimeRotationDrainTest` | 교체 50번이 내린 세대 50개를 모두 닫고 drain 스레드를 남기지 않는다 | 구조적 |
## Recording a baseline ## 기준선 기록하기
When certifying a deployment, record alongside the numbers: the exact command, the commit, hardware, 배포를 인증할 때는 숫자와 함께 이것을 적는다: 정확한 명령, commit, 하드웨어, JVM flag, 시험한 profile YAML,
JVM flags, the profile YAML under test, p50/p95/p99/max, peak heap, peak direct memory, thread count, p50/p95/p99/max, 최대 heap, 최대 direct memory, 스레드 수, connection 수, 물리 시도 수, 오류 수. profile과
connection count, physical attempt count, and error count. A latency figure without its profile and 하드웨어 없는 지연 숫자는 기준선이 아니라 일화다.
hardware is not a baseline; it is an anecdote.
| Field | Value | | 항목 | 값 |
|---|---| |---|---|
| Command | _fill in at certification time_ | | 명령 | _인증할 때 채운다_ |
| Commit | _fill in_ | | Commit | _채운다_ |
| Hardware / JVM | _fill in_ | | 하드웨어 / JVM | _채운다_ |
| Profile under test | _fill in_ | | 시험한 profile | _채운다_ |
| p50 / p95 / p99 / max | _fill in_ | | p50 / p95 / p99 / max | _채운다_ |
| Peak heap / direct memory | _fill in_ | | 최대 heap / direct memory | _채운다_ |
| Threads / connections | _fill in_ | | 스레드 / connection | _채운다_ |
| Physical attempts / errors | _fill in_ | | 물리 시도 / 오류 | _채운다_ |
The table is intentionally left unfilled in the repository: publishing numbers measured on a build 이 표는 저장소에서 일부러 비워 둔다. 빌드 agent에서 잰 숫자를 인증한 기준선처럼 내놓는 것은 기준선이 없는
agent as if they were a certified baseline would be worse than having none. 것보다 나쁘다.
+24 -25
View File
@@ -1,8 +1,8 @@
# HTTP Client Platform — Release Checklist # HTTP Client 플랫폼 — 릴리스 점검표
A release is complete when each item below is demonstrated by a command, not by review. 아래 항목마다 검토가 아니라 명령으로 보여 줬을 때 릴리스가 끝난다.
## Gates ## 게이트
```bash ```bash
cd src cd src
@@ -11,34 +11,33 @@ cd src
./gradlew :adapter:outbound:httpclient:httpClientSecurityTest --console=plain ./gradlew :adapter:outbound:httpclient:httpClientSecurityTest --console=plain
./gradlew :adapter:outbound:httpclient:spring62ApiSurfaceScan --console=plain ./gradlew :adapter:outbound:httpclient:spring62ApiSurfaceScan --console=plain
./gradlew :adapter:outbound:httpclient:spring70CompatibilityTest --console=plain ./gradlew :adapter:outbound:httpclient:spring70CompatibilityTest --console=plain
./gradlew :adapter:outbound:httpclient:httpClientFailureInjectionTest --console=plain # needs Docker ./gradlew :adapter:outbound:httpclient:httpClientFailureInjectionTest --console=plain # Docker 필요
./gradlew :adapter:outbound:httpclient:httpClientPerformanceTest --console=plain # every bound asserted ./gradlew :adapter:outbound:httpclient:httpClientPerformanceTest --console=plain # 모든 상한을 단언
./gradlew verifyCleanArchitectureDependencies --console=plain ./gradlew verifyCleanArchitectureDependencies --console=plain
./gradlew :app-bootstrap:architectureTest --console=plain ./gradlew :app-bootstrap:architectureTest --console=plain
python3 ../scripts/verify-httpclient-docs.py python3 ../scripts/verify-httpclient-docs.py
``` ```
## Completion criteria (design §33) ## 완료 기준 (설계서 §33)
- [ ] Typed clients are the default entry point; H2 and H3 are separately authorised. - [ ] 타입 있는 client가 기본 진입점이다. H2와 H3은 따로 허가한다.
- [ ] H1–H4 cannot bypass timeout, host, TLS, auth, size, or observation policy. - [ ] H1–H4는 timeout, host, TLS, 인증, 크기, 관측 정책을 우회할 수 없다.
- [ ] Apache and JDK produce identical result and exception metadata. - [ ] Apache와 JDK가 같은 결과와 예외 metadata를 낸다.
- [ ] Pool, DNS, connect, TLS, and retry backoff all fit inside the effective deadline. - [ ] pool, DNS, 연결, TLS, 재시도 backoff가 모두 실제 기한 안에 들어간다.
- [ ] Every extra attempt is explained by idempotency, replayability, evidence, deadline, and budget. - [ ] 추가 시도마다 멱등성, 재전송 가능성, 증거, 기한, 예산으로 설명된다.
- [ ] Non-idempotent `SENT_NO_RESPONSE` surfaces as `HttpAmbiguousExecutionException`. - [ ] 멱등이 아닌 `SENT_NO_RESPONSE`는 `HttpAmbiguousExecutionException`으로 드러난다.
- [ ] Pool and buffers are reclaimed after unread bodies, decode errors, cancels, and size rejections. - [ ] 읽지 않은 본문, 디코딩 오류, 취소, 크기 거부 뒤에 pool과 buffer를 되찾는다.
- [ ] OAuth2 refresh is single-flight and 401 replay happens at most once. - [ ] OAuth2 갱신은 한 번만 날아가고, 401 재전송은 많아야 한 번이다.
- [ ] Trust-all and hostname-verification bypass fail at startup. - [ ] trust-all과 hostname 검증 우회는 시작 때 실패한다.
- [ ] Canonicalisation, DNS/IP validation, redirect revalidation, and egress control all pass. - [ ] 정규화, DNS/IP 검증, redirect 재검증, egress 통제가 모두 통과한다.
- [ ] No transparent retry occurs after the first delivered byte. - [ ] 첫 바이트를 넘긴 뒤에는 투명한 재시도가 일어나지 않는다.
- [ ] The negotiated wire protocol matches what the support matrix claims per transport. - [ ] 협상한 wire protocol이 support matrix가 transport마다 주장하는 것과 맞는다.
- [ ] Logical calls and attempts are separate metrics with no forbidden label. - [ ] 논리 호출과 시도는 따로 된 metric이고 금지 label이 없다.
- [ ] DNS, pool, TLS, reset, partial response, and HTTP/2 GOAWAY are reproducible. - [ ] DNS, pool, TLS, reset, 부분 응답, HTTP/2 GOAWAY를 재현할 수 있다.
- [ ] Thread, heap, direct memory, pool, and retry budget bounds hold. - [ ] 스레드, heap, direct memory, pool, 재시도 예산 상한이 지켜진다.
- [ ] The support matrix, configuration reference, security guide and runbook match the code. - [ ] support matrix, 설정 참조, 보안 안내, runbook이 코드와 맞는다.
## Experimental ## Experimental
Jetty HTTP/3 stays Experimental until `Http3CapabilityReport` reports QUIC and TLS 1.3 and the Jetty HTTP/3은 `Http3CapabilityReport`가 QUIC와 TLS 1.3을 보고하고, 그것이 선언한 계약 부분집합이 전용 환경에서
contract subset it declares passes in a dedicated environment. It is never auto-configured by the 통과할 때까지 Experimental로 남는다. Stable starter가 자동 구성하는 일은 없다.
Stable starter.
+46 -47
View File
@@ -1,44 +1,43 @@
# HTTP Client Platform — Repository Adaptation Contract # HTTP Client 플랫폼 — 저장소 적응 계약
**Design source:** `docs/design/2026-08-08-httpclient-platform-design.md` **설계서:** `docs/design/2026-08-08-httpclient-platform-design.md`
**Plan source:** `docs/history/plans/2026-08-08-httpclient-platform-implementation-plan.md` **계획서:** `docs/history/plans/2026-08-08-httpclient-platform-implementation-plan.md`
The design package states its own adaptation rule: 설계 패키지는 자기 적응 규칙을 스스로 밝힌다.
> 실제 Backend Skeleton 저장소가 제공되지 않았으므로 package 경로와 Gradle 구조는 설계서의 명시적 > 실제 Backend Skeleton 저장소가 제공되지 않았으므로 package 경로와 Gradle 구조는 설계서의 명시적
> 구현 가정이다. 구현 전 저장소의 기존 convention과 root package에 맞춰 경로만 조정하고 공개 계약과 > 구현 가정이다. 구현 전 저장소의 기존 convention과 root package에 맞춰 경로만 조정하고 공개 계약과
> 정책 의미론은 유지한다. > 정책 의미론은 유지한다.
This file is the single record of *how* the design's assumed layout was mapped onto this repository. 이 파일은 설계가 가정한 배치를 이 저장소에 *어떻게* 옮겼는지 적은 유일한 기록이다. 바뀐 것은 경로, 빌드 DSL,
Only paths, build DSL, and composition-root ownership changed. Public contracts, policy order, and 조립 루트의 소유뿐이다. 공개 계약, 정책 순서, 오류 의미는 명세대로 구현했다.
error semantics are implemented exactly as specified.
## 1. Why the module layout differs ## 1. 모듈 배치가 다른 이유
The design assumes a greenfield library with 19 Gradle projects under `modules/httpclient/`. 설계는 `modules/httpclient/` 아래에 Gradle 프로젝트 19개를 둔 새 라이브러리를 가정한다. 이 저장소는 Clean
This repository is a Clean Architecture template whose **fail-closed registry** Architecture 템플릿이고, **닫힌 쪽으로 실패하는 registry**(`src/config/architecture/modules.json`)가 Gradle 프로젝트
(`src/config/architecture/modules.json`, enforced by `src/settings.gradle` and 목록을 정한다. `src/settings.gradle`이 registry에 있는 프로젝트만 포함하고, `verifyCleanArchitectureDependencies`가
`verifyCleanArchitectureDependencies`) declares **exactly 19 leaf identities**. Creating 19 more 허용하지 않은 의존을 막는다. leaf 목록은 registry가 정본이다. 설계의 모듈마다 Gradle 프로젝트를 만들면
Gradle projects would violate HARD-STOP #5 in `AGENTS.md`. `AGENTS.md`의 HARD-STOP 5번(registry·Gradle 의존성 검증 위반)에 걸린다.
Therefore the design's 19 library modules become **package boundaries inside the registered leaf** 그래서 설계의 라이브러리 모듈은 등록된 leaf `:adapter:outbound:httpclient` **안의 package 경계**가 된다. 이 저장소
`:adapter:outbound:httpclient`, with two exceptions driven by this repository's own rules: 자신의 규칙 때문에 예외가 둘 있다.
| Design module | Repository home | Reason | | 설계 모듈 | 저장소 위치 | 이유 |
|---|---|---| |---|---|---|
| `httpclient-spring-boot-starter` | `:adapter:outbound:httpclient` (`dev.caskeleton.adapter.outbound.httpclient.autoconfigure`) | Capability-specific Spring composition is owned with the reusable HTTP client platform; `app-bootstrap` only selects/includes the capability and runtime activation remains `app.httpclient.enabled`. | | `httpclient-spring-boot-starter` | `:adapter:outbound:httpclient`(`dev.caskeleton.adapter.outbound.httpclient.autoconfigure`) | capability 전용 Spring 조립은 재사용하는 HTTP client 플랫폼과 함께 둔다. `app-bootstrap`은 capability를 고르고 포함할 뿐이고, 런타임 활성화는 `app.httpclient.enabled`로 남는다. |
| `httpclient-testkit` | `:adapter:outbound:httpclient` `src/testFixtures/java/**/testkit` | The design forbids production modules depending on the testkit. Gradle `testFixtures` publishes the reusable test support only to test consumers; ordinary tests, integration/performance lanes, and JMH opt into that surface explicitly without exposing it to production. `PlatformClasses` excludes test-fixture output so the boundary rules keep meaning production classes. | | `httpclient-testkit` | `:adapter:outbound:httpclient` `src/testFixtures/java/**/testkit` | 설계는 production 모듈이 testkit에 의존하는 것을 금한다. Gradle `testFixtures`는 재사용 테스트 지원을 테스트 소비자에게만 내놓는다. 보통 테스트, integration/performance lane, JMH는 그 면을 명시적으로 골라 쓰고 production에는 드러나지 않는다. `PlatformClasses`는 test-fixture 출력을 빼서 경계 규칙이 계속 production 클래스만 뜻하게 한다. |
The package boundary is enforced by ArchUnit rules (`PublicApiArchitectureTest`, package 경계는 설계의 모듈 의존 표를 재현한 ArchUnit 규칙(`PublicApiArchitectureTest`,
`HttpClientModuleBoundaryTest`) that reproduce the design's module dependency table. `HttpClientModuleBoundaryTest`)이 강제한다.
## 2. Package mapping ## 2. Package 대응
Root package: `io.backend.skeleton.httpclient` → `dev.caskeleton.adapter.outbound.httpclient`. Root package: `io.backend.skeleton.httpclient` → `dev.caskeleton.adapter.outbound.httpclient`.
| Design module | Design package | Repository package | | 설계 모듈 | 설계 package | 저장소 package |
|---|---|---| |---|---|---|
| `httpclient-core-api` | `…httpclient.api` (+ `.body`, `.error`, `.operation`, `.result`) | `dev.caskeleton.adapter.outbound.httpclient.api` (+ same subpackages) | | `httpclient-core-api` | `…httpclient.api` (+ `.body`, `.error`, `.operation`, `.result`) | `dev.caskeleton.adapter.outbound.httpclient.api` (+ 같은 하위 package) |
| `httpclient-profile` | `…httpclient.profile` | `…outbound.httpclient.profile` | | `httpclient-profile` | `…httpclient.profile` | `…outbound.httpclient.profile` |
| `httpclient-transport-spi` | `…httpclient.transport` | `…outbound.httpclient.transport` | | `httpclient-transport-spi` | `…httpclient.transport` | `…outbound.httpclient.transport` |
| `httpclient-transport-apache` | `…httpclient.apache` | `…outbound.httpclient.apache` | | `httpclient-transport-apache` | `…httpclient.apache` | `…outbound.httpclient.apache` |
@@ -48,38 +47,38 @@ Root package: `io.backend.skeleton.httpclient` → `dev.caskeleton.adapter.outbo
| `httpclient-auth` | `…httpclient.auth` | `…outbound.httpclient.auth` | | `httpclient-auth` | `…httpclient.auth` | `…outbound.httpclient.auth` |
| `httpclient-security` | `…httpclient.security` | `…outbound.httpclient.security` | | `httpclient-security` | `…httpclient.security` | `…outbound.httpclient.security` |
| `httpclient-observability` | `…httpclient.observation` | `…outbound.httpclient.observation` | | `httpclient-observability` | `…httpclient.observation` | `…outbound.httpclient.observation` |
| `httpclient-transport-reactor-netty` | `…httpclient.reactor` | removed (decision 9, 2026-09-25: blocking only) | | `httpclient-transport-reactor-netty` | `…httpclient.reactor` | 지움(결정 9, 2026-09-25: blocking만) |
| `httpclient-webclient` | `…httpclient.webclient` | removed (decision 9, 2026-09-25: blocking only) | | `httpclient-webclient` | `…httpclient.webclient` | 지움(결정 9, 2026-09-25: blocking만) |
| `httpclient-service-client` | `…httpclient.service` | `…outbound.httpclient.service` | | `httpclient-service-client` | `…httpclient.service` | `…outbound.httpclient.service` |
| `httpclient-dynamic-target` | `…httpclient.dynamic` | `…outbound.httpclient.dynamic` | | `httpclient-dynamic-target` | `…httpclient.dynamic` | `…outbound.httpclient.dynamic` |
| `httpclient-jetty-http3-experimental` | `…httpclient.http3` | `…outbound.httpclient.http3` | | `httpclient-jetty-http3-experimental` | `…httpclient.http3` | `…outbound.httpclient.http3` |
| `httpclient-spring-boot-starter` | `…httpclient.autoconfigure` | `dev.caskeleton.adapter.outbound.httpclient.autoconfigure` | | `httpclient-spring-boot-starter` | `…httpclient.autoconfigure` | `dev.caskeleton.adapter.outbound.httpclient.autoconfigure` |
| `httpclient-testkit` | `…httpclient.testkit` | `…outbound.httpclient.testkit` (`testkit` source set) | | `httpclient-testkit` | `…httpclient.testkit` | `…outbound.httpclient.testkit` (`testFixtures` source set) |
## 3. Other deliberate substitutions ## 3. 그 밖에 일부러 바꾼 것
| Design assumption | Repository reality | Adaptation | | 설계 가정 | 저장소 현실 | 적응 |
|---|---|---| |---|---|---|
| Gradle Kotlin DSL, `build-logic` convention plugin | Groovy DSL, root `build.gradle` conventions, `LockMode.STRICT` dependency locking | Dependencies declared in `src/adapter/outbound/httpclient/build.gradle`; `gradle.lockfile` regenerated. | | Gradle Kotlin DSL, `build-logic` convention plugin | Groovy DSL, root `build.gradle` convention, `LockMode.STRICT` 의존성 잠금 | 의존성은 `src/adapter/outbound/httpclient/build.gradle`에 선언하고 `gradle.lockfile`을 다시 만들었다. |
| Spring Framework 6.2 baseline with 7.0 compatibility | Spring Boot 4.0.8 / Spring Framework 7.0 is the repository baseline | Common code targets the Spring 6.2 **API surface** (no 6.2-only or 7.0-only classes in common packages). The Spring 7 HTTP Service Group integration and the `RestTemplate` migration package were removed. | | Spring Framework 6.2 기준, 7.0 호환 | 저장소 기준은 Spring Boot 4.0 계열 / Spring Framework 7.0이다. 정확한 버전은 `src/gradle/libs.versions.toml`의 `springBoot`다 | 공통 코드는 Spring 6.2 **API 면**을 대상으로 한다(공통 package에 6.2 전용이나 7.0 전용 클래스가 없다). Spring 7 HTTP Service Group 통합과 `RestTemplate` 이전 package는 지웠다. |
| `settings.gradle.kts` module registration | Fail-closed registry | No registry change; leaf identity, gradle path, allowed dependencies unchanged. | | `settings.gradle.kts` 모듈 등록 | 닫힌 쪽으로 실패하는 registry | registry는 바꾸지 않았다. leaf 식별자, gradle path, 허용 의존은 그대로다. |
| Design §6.2 grades Apache HttpClient 5 as HTTP/2-capable | Spring's blocking factory drives Apache's **classic** client, which is HTTP/1.1 only; HTTP/2 lives in Apache's async client | `ApacheBlockingTransportProvider` declares HTTP/1.1 and rejects an HTTP/2 profile at startup. Blocking HTTP/2 is served by the JDK transport, measured by `NegotiatedProtocolContractTest`. | | 설계 §6.2는 Apache HttpClient 5를 HTTP/2 가능으로 등급 매긴다 | Spring의 blocking factory는 Apache의 **classic** client를 쓰고, 그것은 HTTP/1.1만 한다. HTTP/2는 Apache의 async client에 있다 | `ApacheBlockingTransportProvider`는 HTTP/1.1을 선언하고 HTTP/2 profile을 시작 때 거부한다. blocking HTTP/2는 JDK transport가 맡고, `NegotiatedProtocolContractTest`가 잰다. |
| Design §28.1 names WireMock for stateful fixtures | WireMock's Jetty modules bind a different Jetty 12 ABI than the Boot-managed one this module already needs for HTTP/3, and fail at server start | `StatefulUpstream` provides path-keyed stateful responses on the existing fixture server; the WireMock dependency was removed rather than worked around with a shaded jar | | 설계 §28.1은 상태 있는 fixture로 WireMock을 든다 | WireMock의 Jetty 모듈은 이 모듈이 HTTP/3 때문에 이미 쓰는 Boot 관리 Jetty 12와 ABI가 달라 서버 시작에서 실패한다 | `StatefulUpstream`이 기존 fixture 서버 위에서 경로별 상태 있는 응답을 준다. shaded jar로 돌아가지 않고 WireMock 의존성을 지웠다 |
| Per-task `git commit` | `AGENTS.md`: commit policy is `human-only` | Implementation is delivered unstaged; commits are the human's action. This is the only plan step intentionally not executed, and it is recorded here. | | 작업마다 `git commit` | `AGENTS.md`: 커밋 정책은 `human-only` | 구현은 stage하지 않은 채 넘겼고, 커밋은 사람이 했다. 계획 중 일부러 실행하지 않은 단계는 이것 하나이고, 여기 적어 둔다. |
| `docs/httpclient/**`, `.github/workflows/httpclient-*.yml`, `scripts/verify-httpclient-docs.py` | Repository already owns `docs/` and `.github/workflows/` | Created at the same repository-relative paths. | | `docs/httpclient/**`, `.github/workflows/httpclient-*.yml`, `scripts/verify-httpclient-docs.py` | 저장소가 이미 `docs/`와 `.github/workflows/`를 가진다 | 같은 저장소 상대 경로에 만들었다. |
## 4. What is unchanged from the design ## 4. 설계에서 바뀌지 않은 것
- H1 / H2 / H3 / H4 exposure rules and the forbidden native-engine signatures. - H1 / H2 / H3 / H4 노출 규칙과 금지한 native 엔진 시그니처.
- `ExecutionEvidence`, `BodyReplayability`, `OperationIdempotency`, `AttemptStage`, `FailureCategory`. - `ExecutionEvidence`, `BodyReplayability`, `OperationIdempotency`, `AttemptStage`, `FailureCategory`.
- `HttpOperation`, `HttpCallResult`, `BodySource`, `ResponseType`, `BlockingStreamingResponse`. - `HttpOperation`, `HttpCallResult`, `BodySource`, `ResponseType`, `BlockingStreamingResponse`.
- The complete stable exception hierarchy and `HttpFailureMetadata` redaction rules. - 안정된 예외 계층 전체와 `HttpFailureMetadata` 가리기 규칙.
- Named Client Profile schema, startup validation codes, and operation override direction. - Named Client Profile schema, 시작 검증 코드, 연산 덮어쓰기 방향.
- Effective deadline formula, attempt budget, and streaming setup/idle split. - 실제 기한 공식, 시도 예산, 스트리밍의 준비/idle 분리.
- Retry eligibility inputs, the ordered decision table, retry budget, and backoff rules. - 재시도 자격 입력, 순서 있는 판정 표, 재시도 예산, backoff 규칙.
- Circuit → Rate Limiter → Bulkhead attempt order and logical admission placement. - Circuit → Rate Limiter → Bulkhead 시도 순서와 논리 허가 위치.
- OAuth2 cache key, single-flight refresh, and the 401 replay-at-most-once rule. - OAuth2 cache key, 한 번만 날아가는 갱신, 401 재전송은 많아야 한 번이라는 규칙.
- TLS allow/forbid lists and permanent-failure classification. - TLS 허용/금지 목록과 영구 실패 분류.
- Dynamic Target canonicalization → all-answer DNS validation → pinning → redirect revalidation. - Dynamic Target 정규화 → 모든 DNS 답 검증 → 고정 → redirect 재검증.
- Low-cardinality tag allowlist, forbidden labels, trace and logging rules. - 가짓수가 적은 tag 허용 목록, 금지 label, trace와 로그 규칙.
- Runtime generation swap and drain semantics. - 런타임 세대 교체와 drain 의미.
+59 -66
View File
@@ -1,87 +1,80 @@
# Retry and Ambiguity # 재시도와 결과 모름
The platform never decides a retry from the HTTP method alone (design D-09). A second attempt 플랫폼은 HTTP method만 보고 재시도를 정하지 않는다(설계 D-09). 두 번째 시도는 멱등성, 본문 재전송 가능성, 실행
happens only when idempotency, body replayability, execution evidence, deadline, and retry budget 증거, 기한, 재시도 예산이 모두 허락할 때만 일어난다.
all permit it.
## Execution evidence ## 실행 증거
| Evidence | Meaning | Typical cause | | 증거 | 뜻 | 흔한 원인 |
|---|---|---| |---|---|---|
| `NOT_SENT` | Proven that the server never received the request | profile rejection, pool timeout, DNS failure, connect failure, pre-request TLS failure, HTTP/2 `REFUSED_STREAM` | | `NOT_SENT` | 서버가 요청을 받지 않았음이 증명됐다 | profile 거부, pool 시간 초과, DNS 실패, 연결 실패, 요청 전 TLS 실패, HTTP/2 `REFUSED_STREAM` |
| `SENT_NO_RESPONSE` | Some or all of the request was written, no final header arrived | partial write, response-header timeout, connection reset | | `SENT_NO_RESPONSE` | 요청 일부나 전부를 썼고, 최종 헤더가 오지 않았다 | 부분 쓰기, 응답 헤더 시간 초과, connection reset |
| `RESPONSE_RECEIVED` | Final headers arrived, whatever the status | 2xx, 4xx, 5xx, redirect | | `RESPONSE_RECEIVED` | 상태와 상관없이 최종 헤더가 왔다 | 2xx, 4xx, 5xx, redirect |
| `PARTIAL_RESPONSE` | Headers and part of the body arrived | reset during decode, interrupted stream | | `PARTIAL_RESPONSE` | 헤더와 본문 일부가 왔다 | 디코딩 중 reset, 끊긴 stream |
`NOT_SENT` is only produced by a stage failure that proves it. A generic engine I/O error is never `NOT_SENT`는 그것을 증명하는 단계 실패만 만든다. 일반 엔진 I/O 오류는 절대 `NOT_SENT`로 올리지 않는다. 시간
upgraded to `NOT_SENT`, because that is exactly how a timeout becomes a duplicate payment. 초과가 이중 결제가 되는 길이 바로 그것이기 때문이다.
## Body replayability ## 본문 재전송 가능성
| Body | Replayability | | 본문 | 재전송 가능성 |
|---|---| |---|---|
| immutable `byte[]` | `REPLAYABLE` | | 바뀌지 않는 `byte[]` | `REPLAYABLE` |
| DTO plus a deterministic codec | `REPLAYABLE` | | DTO와 결정적 codec | `REPLAYABLE` |
| reopenable file or resource supplier | `REOPENABLE` | | 다시 열 수 있는 파일이나 resource supplier | `REOPENABLE` |
| a single `InputStream` instance | `ONE_SHOT` | | `InputStream` 인스턴스 하나 | `ONE_SHOT` |
| publisher factory | as declared | | publisher factory | 선언한 대로 |
| publisher instance | `ONE_SHOT` | | publisher 인스턴스 | `ONE_SHOT` |
| multipart | the weakest part | | multipart | 가장 약한 part를 따른다 |
## Decision order ## 판정 순서
`DefaultRetryEligibilityEngine` evaluates in this order, and a later rule can never re-enable `DefaultRetryEligibilityEngine`은 이 순서로 판정한다. 뒤 규칙은 앞 규칙이 금지한 것을 절대 다시 허락하지 못한다.
something an earlier one forbade:
1. `SENT_NO_RESPONSE` on an operation that is not safely idempotent → `AmbiguousFailure` 1. 안전하게 멱등이 아닌 연산의 `SENT_NO_RESPONSE` → `AmbiguousFailure`
2. attempts exhausted → `RetryDenied.maxAttempts()` 2. 시도를 다 썼다 → `RetryDenied.maxAttempts()`
3. retry budget empty → `RetryDenied.budgetExhausted()` 3. 재시도 예산이 비었다 → `RetryDenied.budgetExhausted()`
4. body not replayable → `RetryDenied.bodyNotReplayable()` 4. 본문을 재전송할 수 없다 → `RetryDenied.bodyNotReplayable()`
5. first byte already delivered → `RetryDenied.responseAlreadyDelivered()` 5. 첫 바이트를 이미 넘겼다 → `RetryDenied.responseAlreadyDelivered()`
6. runtime draining → `RetryDenied.runtimeDraining()` 6. 런타임이 비우는 중이다 → `RetryDenied.runtimeDraining()`
7. remaining deadline below the minimum attempt budget → `RetryDenied.deadline()` 7. 남은 기한이 최소 시도 예산보다 작다 → `RetryDenied.deadline()`
8. permanent failure category → `RetryDenied.permanentFailure(...)` 8. 영구 실패 범주 → `RetryDenied.permanentFailure(...)`
9. `PARTIAL_RESPONSE` on an operation that is not safely idempotent → `AmbiguousFailure` 9. 안전하게 멱등이 아닌 연산의 `PARTIAL_RESPONSE` → `AmbiguousFailure`
10. status- and failure-specific rules 10. 상태별·실패별 규칙
Ambiguity comes first because it describes the outcome, not whether another attempt is allowed. It 결과 모름이 맨 앞인 것은 그것이 다른 시도가 허락되는지가 아니라 결과를 설명하기 때문이다. 예전에는 시도 검사
used to sit below the attempt check, so with the default `max-attempts: 1` a POST that timed out 아래에 있었다. 그래서 기본값 `max-attempts: 1`에서는 보낸 뒤 시간이 넘은 POST가 호출자에게 보통의 시간 초과로
after it was sent reached the caller as an ordinary timeout (review 2026-11-01 05-14). 도착했다(리뷰 2026-11-01 05-14).
## Status rules ## 상태 규칙
| Status | Decision | | 상태 | 판정 |
|---|---| |---|---|
| 408 | retry inside deadline and budget | | 408 | 기한과 예산 안에서 재시도 |
| 425 | at most one retry, first attempt only | | 425 | 첫 시도에서만, 많아야 한 번 재시도 |
| 429 | retry inside `Retry-After`, deadline, and budget | | 429 | `Retry-After`, 기한, 예산 안에서 재시도 |
| 401 | one refresh-and-replay, safe replayable operations only. The credential is refreshed only once the retry is granted; a 401 that will not be replayed (one attempt, no budget, no deadline) leaves the token cache alone | | 401 | 안전하고 재전송 가능한 연산에서만 갱신 후 재전송 한 번. credential은 재시도를 허락받은 뒤에만 갱신한다. 재전송하지 않을 401(시도 한 번, 예산 없음, 기한 없음)은 token cache를 건드리지 않는다 |
| 500 | denied unless the upstream registered it as transient **and** the operation is safely idempotent | | 500 | upstream이 일시적이라고 등록했고 **그리고** 연산이 안전하게 멱등일 때만 허락. 아니면 거부 |
| 502, 503, 504 | retry for safely idempotent operations; ambiguous otherwise | | 502, 503, 504 | 안전하게 멱등인 연산은 재시도. 아니면 결과 모름 |
| other 4xx | denied | | 그 밖의 4xx | 거부 |
## Ambiguity ## 결과 모름
A non-idempotent request that reached `SENT_NO_RESPONSE` raises 멱등이 아닌 요청이 `SENT_NO_RESPONSE`에 닿으면 `HttpAmbiguousExecutionException`을 던진다. 일부러 만든 세 번째
`HttpAmbiguousExecutionException`. It is a third answer on purpose: retrying may duplicate a side 답이다. 재시도하면 부수 효과가 두 번 날 수 있고, 보통의 실패로 알리면 요청이 일어나지 않았다고 호출자에게 말하는
effect, and reporting a plain failure would tell the caller the request did not happen, which may 셈인데 그것이 거짓일 수 있다. 호출자는 맞춰 본다. 보통 upstream에 조회하거나 멱등 key로 다시 보낸다.
be false. The caller reconciles, usually by querying the upstream or replaying with an idempotency
key.
### Where the evidence comes from ### 증거는 어디서 오나
Whether a failed request was sent is read from the stage the attempt reached and the engine's 실패한 요청을 보냈는지는 시도가 닿은 단계와 엔진의 예외 타입에서 읽는다. Apache는 맺은 connection에 요청을 쓰기
exception type. Apache reports the moment it starts writing the request onto an established 시작하는 순간을 알려 준다(`RequestWriteSignal`). 그래서 빌리기, 풀기, 연결, TLS handshake 중의 실패는 엔진이 일반
connection (`RequestWriteSignal`), so a failure while leasing, resolving, connecting or completing 예외를 던져도 `NOT_SENT`다. 그 순간을 알려 주지 못하는 transport(JDK, Jetty)는 엔진을 부른 순간부터 쓰는 중으로
the TLS handshake is `NOT_SENT` even when the engine throws a generic exception. Transports that 본다. 「안 보냈다」고 짐작하는 것이 시간 초과를 이중 결제로 바꾸기 때문이다. HTTP/2 `REFUSED_STREAM` frame은
cannot report that moment (JDK, Jetty) are treated as writing from the moment the engine is called, 상대가 아무것도 처리하지 않았다는 증거이고, 예외 변환을 거쳐도 `NOT_SENT`로 남는다.
because guessing "not sent" is what turns a timeout into a duplicate payment. An HTTP/2
`REFUSED_STREAM` frame is proof the peer processed nothing and is kept as `NOT_SENT` through
exception mapping.
## Budget and backoff ## 예산과 backoff
Retry tokens come from a per-upstream token bucket sized as a fraction of real traffic, so a failing 재시도 token은 실제 트래픽의 일정 비율로 크기를 정한 upstream별 token bucket에서 나온다. 그래서 건강한 인스턴스
upstream cannot be flooded by retries from a healthy fleet. Backoff is exponential with full or 무리가 실패하는 upstream을 재시도로 덮치지 못한다. backoff는 full이나 decorrelated jitter를 쓰는 지수 backoff이고,
decorrelated jitter, bounded by `max-backoff`, by `Retry-After`, and by the remaining deadline. No `max-backoff`, `Retry-After`, 남은 기한으로 제한한다. backoff를 기다리는 동안에는 connection도 bulkhead 허가도
connection and no bulkhead permit is held while a backoff is waiting. 잡지 않는다.
+46 -53
View File
@@ -1,75 +1,68 @@
# HTTP Client Platform — Security Guide # HTTP Client 플랫폼 — 보안 안내
## What the platform owns ## 플랫폼이 소유하는 것
`Authorization`, `Proxy-Authorization`, `Host`, `Content-Length`, `Transfer-Encoding`, `Authorization`, `Proxy-Authorization`, `Host`, `Content-Length`, `Transfer-Encoding`, `Traceparent`,
`Traceparent`, `Tracestate`, `Baggage`, and (unless a profile opts in) `Cookie` are platform-owned. `Tracestate`, `Baggage`, 그리고 (profile이 고르지 않는 한) `Cookie`는 플랫폼이 소유한다. 호출자는 이것들을 정할 수
A caller cannot set them. `Idempotency-Key` is accepted only when the operation declares it. Any 없다. `Idempotency-Key`는 연산이 선언했을 때만 받는다. 이름이나 값에 CR이나 LF가 있는 헤더는 요청을 만들기 전에
header name or value containing CR or LF is rejected before the request is built. 거부한다.
## Target policy ## 대상 정책
A trusted profile accepts only a profile-relative URI template. An absolute URI is rejected rather trusted profile은 profile 기준 상대 URI template만 받는다. 절대 URI는 정리하지 않고 거부한다. 목적지를 바꾸는 것은
than sanitised: varying the destination is what H3 is for, and H3 has its own policy, credentials, H3가 하는 일이고, H3에는 자기 정책, credential, 주소 검증이 있다. template 변수는 구성 요소마다 인코딩한다. 그래서
and address validation. Template variables are encoded per component, so a value containing `/`, `/`, `?`, `#`이 든 값도 요청의 모양을 바꾸지 못한다.
`?`, or `#` cannot change the shape of the request.
## TLS ## TLS
Allowed: TLS 1.2 and 1.3, hostname verification, the JVM trust store, a per-profile custom CA, a 허락: TLS 1.2와 1.3, hostname 검증, JVM trust store, profile별 사설 CA, profile별 client 인증서, mTLS, SNI와
per-profile client certificate, mTLS, SNI and ALPN, and certificate rotation through a new runtime ALPN, 새 런타임 세대를 통한 인증서 교체.
generation.
Forbidden and unrepresentable: a trust-all trust manager, disabled hostname verification, ignoring 금지하고 표현할 수도 없음: 모두 믿는 trust manager, hostname 검증 끄기, 인증서 오류 무시, 운영의 자체 서명 인증서를
certificate errors, automatically trusting a production self-signed certificate, falling back to 자동으로 믿기, HTTPS 실패 뒤 평문으로 물러서기, key 재료를 설정이나 로그에 쓰기.
plaintext after an HTTPS failure, and writing key material into configuration or logs.
Unknown CA, hostname mismatch, expired certificate, revoked certificate, protocol mismatch, and a 모르는 CA, hostname 불일치, 만료한 인증서, 폐기된 인증서, protocol 불일치, 빠진 client 인증서는 영구 실패다.
missing client certificate are permanent. Only a transient handshake timeout may be retried, inside 일시적인 handshake 시간 초과만 기한 안에서 재시도할 수 있다.
the deadline.
## Dynamic Target (SSRF) ## Dynamic Target (SSRF)
Every hop — the first one included — runs the whole flow: 첫 hop을 포함해 모든 hop이 흐름 전체를 돈다.
1. strict URI parse 1. 엄격한 URI 파싱
2. scheme allowlist 2. scheme 허용 목록
3. reject userinfo and invalid ports 3. userinfo와 잘못된 port 거부
4. IDNA-canonicalise the host 4. host를 IDNA로 정규화
5. host allowlist or suffix policy 5. host 허용 목록이나 접미사 정책
6. resolve **every** A and AAAA answer 6. A와 AAAA 답을 **모두** 푼다
7. normalise each address, including IPv4-mapped IPv6 7. IPv4-mapped IPv6를 포함해 주소마다 정규화
8. reject loopback, link-local, RFC1918, ULA, carrier-grade NAT, unspecified, multicast, cloud 8. loopback, link-local, RFC1918, ULA, carrier-grade NAT, 미지정, multicast, cloud metadata, 조직이 정한 범위를
metadata, and organisation-defined ranges 거부
9. pin the connection to the approved addresses through the same validated resolver 9. 같은 검증 resolver로 connection을 승인한 주소에 고정
10. apply response size and content policy 10. 응답 크기와 content 정책 적용
11. repeat for each redirect 11. redirect마다 반복
Any forbidden address in the answer set rejects the whole target. Validating only the first answer 답 묶음에 금지 주소가 하나라도 있으면 대상 전체를 거부한다. 첫 답만 검증하면 공개 주소 하나와 사설 주소 하나로
would let a host that resolves to one public and one private address through. 풀리는 host가 통과한다.
Dynamic profiles inherit no API key, OAuth token, Cookie, or default header, and no Cookie jar is dynamic profile은 API key, OAuth token, Cookie, 기본 헤더를 물려받지 않고, Cookie jar도 만들지 않는다. 특정 host에
created. A specific host may be granted a credential only through an explicitly registered credential을 주려면 명시적으로 등록한 `DynamicCredentialBinding`을 거쳐야만 한다.
`DynamicCredentialBinding`.
Application-level validation is not sufficient on its own. A network control — Kubernetes 애플리케이션 수준 검증만으로는 충분하지 않다. 네트워크 통제(Kubernetes NetworkPolicy, service mesh egress 정책,
NetworkPolicy, service-mesh egress policy, firewall, or proxy ACL — is an operational completion 방화벽, proxy ACL)가 운영 완료 요건이다.
requirement.
## Redirects ## Redirect
Disabled by default. Engine redirect handling is off in every transport so the platform can 기본으로 꺼져 있다. 플랫폼이 hop마다 다시 검증할 수 있게 모든 transport에서 엔진의 redirect 처리를 끈다. 307과
re-validate each hop. 307 and 308 preserve method and body and are therefore allowed only for a 308은 method와 본문을 유지하므로 재전송 가능한 본문일 때만 허락한다. origin을 넘는 hop은 profile이 고르지 않으면
replayable body. Cross-origin hops are refused unless the profile opts in, and when they are 거부하고, 허락하면 `Authorization`, `Proxy-Authorization`, `Cookie`, API key 헤더를 지운다.
allowed `Authorization`, `Proxy-Authorization`, `Cookie`, and API-key headers are stripped.
## Observability ## 관측
Allowed tags: `clientName`, `operationName`, `method`, `uriTemplate`, `status`, `outcome`, 허락한 tag: `clientName`, `operationName`, `method`, `uriTemplate`, `status`, `outcome`, `transport`,
`transport`, `protocol`, `timeoutType`, `retryReason`, `evidence`, `circuitState`. `protocol`, `timeoutType`, `retryReason`, `evidence`, `circuitState`.
Rejected outright: full URL, query parameters, path variable values, user ID, raw tenant ID, 바로 거부: 전체 URL, query parameter, 경로 변수 값, user ID, 날것의 tenant ID, 푼 IP, API key, token, Cookie, 멱등
resolved IP, API key, token, Cookie, idempotency key, request or response body, exception message. key, 요청이나 응답 본문, 예외 메시지.
Failures are logged once, structured, at the end of a logical call. Retry attempts are DEBUG or span 실패는 논리 호출 끝에 구조화해서 한 번 로그를 남긴다. 재시도 시도는 DEBUG이거나 span event다. URL은 template로만
events. URLs appear only as templates. 나온다.
+21 -23
View File
@@ -1,36 +1,34 @@
# Streaming and Large Bodies # 스트리밍과 큰 본문
## Response lifecycle ## 응답 수명
A streaming download returns `BlockingStreamingResponse`, never a bare `InputStream`. Closing is 스트리밍 다운로드는 맨 `InputStream`이 아니라 `BlockingStreamingResponse`를 돌려준다. 닫기는 멱등이고, 다 읽은
idempotent and always releases the connection — after a full read, a partial read, a decode failure, 뒤든, 일부만 읽은 뒤든, 디코딩 실패나 크기 거부 뒤든 늘 connection을 돌려준다. 상태는 본문 바이트를 넘기기 전에
or a size rejection. The status is validated before any body byte is delivered, so a failed download 검증한다. 그래서 실패한 다운로드가 호출자가 따져야 하는 반쯤 읽힌 stream이 되지 않는다.
never becomes a half-consumed stream the caller has to reason about.
Wire bytes and decoded bytes are bounded independently, because a compressed payload passes a wire wire 바이트와 디코딩한 바이트는 따로 제한한다. 압축한 payload는 wire 검사를 통과한 뒤 늘어나기 때문이다. 한도는
check and then expands. Limits are enforced while reading, not after buffering. 버퍼링한 뒤가 아니라 읽는 동안 강제한다.
## The first-byte boundary ## 첫 바이트 경계
```text ```text
response headers received 응답 헤더를 받았다
→ nothing delivered yet → 아직 아무것도 넘기지 않았다
→ a read-only operation may still be retried → 읽기 전용 연산은 아직 재시도할 수 있다
→ the response is handed to the caller → 응답을 호출자에게 넘겼다
→ transparent retry is no longer possible → 투명한 재시도는 더는 할 수 없다
``` ```
Retrying after delivery would replay a stream the caller has already partly consumed, producing 넘긴 뒤에 재시도하면 호출자가 이미 일부 읽은 stream을 다시 보내게 된다. 그러면 아래쪽 어느 코드도 알아챌 수 없는
duplicated or reordered data that no downstream code can detect. The streaming gateway hands out 중복되거나 순서가 바뀐 데이터가 생긴다. 스트리밍 gateway는 시도가 끝난 뒤에만 응답을 넘긴다. 그래서 호출자가
the response only after the attempt has finished, so there is no retry left to run once the caller 읽기 시작하면 돌릴 재시도가 남아 있지 않다.
reads.
## Request bodies ## 요청 본문
A reopenable body is opened once per attempt, which is what makes it replayable; reusing the 다시 열 수 있는 본문은 시도마다 한 번 연다. 그래서 재전송할 수 있다. 앞 stream을 다시 쓰면 재시도에서 빈 본문을
previous stream would silently send an empty body on the retry. A one-shot stream is never retried. 조용히 보낸다. 한 번만 쓰는 stream은 절대 재시도하지 않는다.
## Server-sent events ## Server-sent events
The platform has no server-sent-event client. It was part of the reactive stack, which was removed 플랫폼에는 server-sent event client가 없다. 그것은 지운 reactive stack의 일부였다(결정 9, 2026-09-25). 플랫폼은
(decision 9, 2026-09-25): the platform runs blocking calls on the caller's thread only. 호출자의 스레드에서 blocking 호출만 돌린다.
+57 -62
View File
@@ -1,87 +1,82 @@
# HTTP Client Platform — Support Matrix # HTTP Client 플랫폼 — 지원 매트릭스
Grades follow design §6 and §29. A row is **Stable** only when the cross-transport contract suite 등급은 설계서 §6과 §29를 따른다. 행이 **Stable**이려면 transport를 넘는 계약 suite가 그것을 증명해야 한다. suite가
proves it; anything the suite cannot prove is **Experimental** and says so. 증명하지 못하는 것은 **Experimental**이고 그렇다고 밝힌다. 등급 이름(Stable, Default, Restricted, Internal,
Experimental)은 원문 그대로 쓴다.
## Spring API ## Spring API
| API | Grade | Role | Constraint | | API | 등급 | 역할 | 제약 |
|---|---|---|---| |---|---|---|---|
| `RestClient` | Stable | Blocking execution (the only execution model) | Bounded concurrency and an effective deadline are mandatory | | `RestClient` | Stable | blocking 실행(유일한 실행 모델) | 동시성 상한과 실제 기한이 필수다 |
| HTTP Service Client (`@HttpExchange`) | Default | Declarative typed client | Operation metadata is mandatory | | HTTP Service Client(`@HttpExchange`) | Default | 선언형 타입 있는 client | 연산 metadata가 필수다 |
| Generic Exchange (H2) | Restricted | Dynamic method, path, body | Base URL and policy are immutable | | Generic Exchange (H2) | Restricted | 동적 method, 경로, 본문 | Base URL과 정책은 바꿀 수 없다 |
| Dynamic Target (H3) | Restricted | User-supplied URL | Separate SSRF policy; inherits no credential | | Dynamic Target (H3) | Restricted | 사용자가 준 URL | 따로 된 SSRF 정책. credential을 물려받지 않는다 |
| Native engine | Internal | Engine-specific configuration | Never an application-facing API | | Native 엔진 | Internal | 엔진별 설정 | 애플리케이션이 쓰는 API가 절대 아니다 |
## Transports ## Transport
The platform is blocking only (decision 9, 2026-09-25): every call runs on the caller's thread — 플랫폼은 blocking만 한다(결정 9, 2026-09-25). 모든 호출은 호출자의 스레드(이 템플릿에서는 virtual thread)에서
a virtual thread in this template — through `RestClient`. There is no reactive execution path, no `RestClient`를 거쳐 돈다. reactive 실행 경로도, `WebClient`도, Reactor Netty transport도 없다.
`WebClient`, and no Reactor Netty transport.
| Transport | HTTP/1.1 | HTTP/2 | HTTP/3 | Grade | Verified by | | Transport | HTTP/1.1 | HTTP/2 | HTTP/3 | 등급 | 확인하는 것 |
|---|---:|---:|---:|---|---| |---|---:|---:|---:|---|---|
| Apache HttpClient 5 (classic) | yes | **no** | no | Stable (default) | `httpClientStableContractTest`, `NegotiatedProtocolContractTest` | | Apache HttpClient 5 (classic) | 된다 | **안 된다** | 안 된다 | Stable(기본) | `httpClientStableContractTest`, `NegotiatedProtocolContractTest` |
| JDK HttpClient | yes | yes (TLS/ALPN) | no | Stable (lightweight, HTTP/2) | `NegotiatedProtocolContractTest` | | JDK HttpClient | 된다 | 된다(TLS/ALPN) | 안 된다 | Stable(가벼움, HTTP/2) | `NegotiatedProtocolContractTest` |
| Jetty | yes | yes | yes | **Experimental** | `Http3OptInTest` only | | Jetty | 된다 | 된다 | 된다 | **Experimental** | `Http3OptInTest`뿐 |
| Simple request factory | limited | no | no | Local test only | rejected in production by `ClientProfileValidator` | | Simple request factory | 제한적 | 안 된다 | 안 된다 | 로컬 테스트 전용 | 운영에서는 `ClientProfileValidator`가 거부한다 |
### Apache is HTTP/1.1 here, and why ### 여기서 Apache가 HTTP/1.1인 이유
Design §6.2 grades Apache HttpClient 5 as HTTP/2-capable, and the library is — in its **async** 설계서 §6.2는 Apache HttpClient 5를 HTTP/2 가능으로 등급 매긴다. 라이브러리는 그렇다. 다만 **async** client에서다.
client. Spring's `HttpComponentsClientHttpRequestFactory` drives the **classic** client, which Spring의 `HttpComponentsClientHttpRequestFactory`는 **classic** client를 쓰고, 그것은 HTTP/1.1만 한다.
speaks HTTP/1.1 only. `NegotiatedProtocolContractTest` measures this rather than assuming it: the `NegotiatedProtocolContractTest`는 이것을 가정하지 않고 잰다. classic client는 prior-knowledge h2c 서버에 대해
classic client fails outright against a prior-knowledge h2c server. 바로 실패한다.
So `ApacheBlockingTransportProvider.capabilities()` declares HTTP/1.1, and a profile that pairs 그래서 `ApacheBlockingTransportProvider.capabilities()`는 HTTP/1.1을 선언한다. Apache와 `HTTP_2`를 짝지은
Apache with `HTTP_2` is rejected at startup instead of quietly running HTTP/1.1 while this table profile은 이 표가 다르게 주장하는 동안 조용히 HTTP/1.1로 도는 대신 시작 때 거부된다. **HTTP/2는 JDK transport가
claims otherwise. **HTTP/2 is served by the JDK transport**, measured from the client after a real 맡는다.** 설정에서 읽지 않고, 실제 TLS handshake 뒤 client 쪽에서 잰다. HTTP/2만으로 제한할 수 있는 transport는
TLS handshake, not read from configuration. No transport can be restricted to HTTP/2 alone, so a 없으므로 `HTTP_2`만 선언한 profile은 거부한다(`HTTP2_REQUIRED_TRANSPORT_UNSUPPORTED`).
profile that declares only `HTTP_2` is refused (`HTTP2_REQUIRED_TRANSPORT_UNSUPPORTED`).
The JDK transport declares `routeScopedPool=false`, `boundedPendingAcquireQueue=false`, and JDK transport는 `routeScopedPool=false`, `boundedPendingAcquireQueue=false`, `dynamicTargetStable=false`를
`dynamicTargetStable=false`. A profile that needs any of those is rejected at startup rather than 선언한다. 그중 하나라도 필요한 profile은 약한 보장으로 돌지 않고 시작 때 거부된다. 그래서 Apache와 JDK 사이의
served with weaker guarantees. Choosing between Apache and JDK is therefore a real trade: Apache 선택은 진짜 맞바꿈이다. Apache는 route 범위 pool과 Dynamic Target 고정을 주고, JDK는 HTTP/2를 준다.
gives route-scoped pooling and Dynamic Target pinning, JDK gives HTTP/2.
## Capability gates ## Capability 관문
| Capability | Gate | | Capability | 관문 |
|---|---| |---|---|
| Dynamic Target (H3) | Apache only; JDK and Jetty are rejected | | Dynamic Target (H3) | Apache만. JDK와 Jetty는 거부한다 |
| HTTP/3 | `experimentalAcknowledgement` must equal `I_ACCEPT_HTTP3_EXPERIMENTAL_SEMANTICS` | | HTTP/3 | `experimentalAcknowledgement`가 `I_ACCEPT_HTTP3_EXPERIMENTAL_SEMANTICS`와 같아야 한다 |
| Cross-origin redirect | opt-in per profile; credentials are stripped on the hop | | origin을 넘는 redirect | profile마다 골라 켠다. hop에서 credential을 지운다 |
| Retry | evidence-based; never enabled by HTTP method alone | | 재시도 | 증거 기반. HTTP method만으로 켜지지 않는다 |
## CI matrix ## CI 매트릭스
| Profile | Frequency | Release gate | Task | | Profile | 빈도 | 릴리스 게이트 | Task |
|---|---|---|---| |---|---|---|---|
| Spring Framework 7.0 (repository baseline) | PR touching this leaf, main push, release | required | `spring70CompatibilityTest` | | Spring Framework 7.0(저장소 기준) | 이 leaf를 건드린 PR, main push, 릴리스 | 필수 | `spring70CompatibilityTest` |
| Spring Framework 6.2 API surface | every PR (`check`), release | required | `spring62ApiSurfaceScan` | | Spring Framework 6.2 API 면 | 모든 PR(`check`), 릴리스 | 필수 | `spring62ApiSurfaceScan` |
| Apache HC5 + RestClient | PR touching this leaf (both transports together on every PR through `check`), release | required | `httpClientStableContractTest -Phttpclient.contract.transports=apache` | | Apache HC5 + RestClient | 이 leaf를 건드린 PR(두 transport는 `check`로 모든 PR에서 함께 돈다), 릴리스 | 필수 | `httpClientStableContractTest -Phttpclient.contract.transports=apache` |
| JDK HttpClient + RestClient | PR touching this leaf (both transports together on every PR through `check`), release | required | `httpClientStableContractTest -Phttpclient.contract.transports=jdk` | | JDK HttpClient + RestClient | 이 leaf를 건드린 PR(두 transport는 `check`로 모든 PR에서 함께 돈다), 릴리스 | 필수 | `httpClientStableContractTest -Phttpclient.contract.transports=jdk` |
| SSRF / cardinality suite | every PR (`check`), release | required | `httpClientSecurityTest` | | SSRF / 가짓수 suite | 모든 PR(`check`), 릴리스 | 필수 | `httpClientSecurityTest` |
| Toxiproxy fault suite | main push, nightly (`integrationCheck`), release | required | `httpClientFailureInjectionTest` | | Toxiproxy 장애 suite | main push, nightly(`integrationCheck`), 릴리스 | 필수 | `httpClientFailureInjectionTest` |
| Performance certification | main push, nightly (`performanceCheck`), release | required | `httpClientPerformanceTest` (every bound asserted; no switch turns them off) | | 성능 인증 | main push, nightly(`performanceCheck`), 릴리스 | 필수 | `httpClientPerformanceTest`(모든 상한을 단언. 끄는 스위치가 없다) |
| Jetty HTTP/3 | main push, nightly | Experimental, non-blocking | `test -Phttp3.tests.enabled=true` | | Jetty HTTP/3 | main push, nightly | Experimental, 막지 않음 | `test -Phttp3.tests.enabled=true` |
### Known limitation of the Spring 6.2 lane ### Spring 6.2 lane의 알려진 한계
This repository's Spring Boot 4.0 baseline pins Spring Framework 7, so a real 6.2 runtime cannot be 이 저장소의 Spring Boot 4.0 기준은 Spring Framework 7을 고정한다. 그래서 여기서는 실제 6.2 런타임을 풀 수 없다.
resolved here. `spring62ApiSurfaceScan` therefore verifies the **API surface**: the common `spring62ApiSurfaceScan`은 대신 **API 면**을 확인한다. 공통 package가 Spring 7 전용 타입을 참조하지 않아야 하고,
packages must not reference any Spring 7-only type, and no class uses 어떤 클래스도 `org.springframework.web.service.registry`를 쓰지 않아야 한다. 실제 6.2 배포판에 대해 suite를
`org.springframework.web.service.registry`. Executing the suite against an actual 6.2 distribution 돌리려면 그 계열의 host 프로젝트가 필요하다. 이 한계는 통과하는 검사 뒤에 숨기지 않고 밝혀 둔다.
requires a host project on that line. This limitation is stated rather than hidden behind a passing
check.
## Suite가 증명하지 않는 것
## What the suites do not prove 매트릭스를 바람이 아니라 측정으로 읽게 하려고 적는다.
Stated so the matrix is read as a measurement rather than an aspiration. | 빈곳 | 이유 | 대신 증명하는 것 |
| Gap | Why | What is proven instead |
|---|---|---| |---|---|---|
| HTTP/2 frame injection (`REFUSED_STREAM`, arbitrary `GOAWAY`) | The fixture server exposes no frame-level control, and a purpose-built h2 server is a larger dependency than the guarantee is worth here | `Http2EvidenceMapperTest` proves the frame → evidence mapping, and `NegotiatedProtocolContractTest` proves h2 is really negotiated | | HTTP/2 frame 주입(`REFUSED_STREAM`, 임의 `GOAWAY`) | fixture 서버에 frame 수준 제어가 없고, 전용 h2 서버는 여기서 얻는 보장보다 큰 의존성이다 | `Http2EvidenceMapperTest`가 frame → 증거 대응을, `NegotiatedProtocolContractTest`가 h2가 정말 협상되는지를 증명한다 |
| Spring 6.2 runtime | This repository's Boot 4.0 baseline pins Spring 7 | `spring62ApiSurfaceScan` confines the common packages to the 6.2 API surface | | Spring 6.2 런타임 | 이 저장소의 Boot 4.0 기준이 Spring 7을 고정한다 | `spring62ApiSurfaceScan`이 공통 package를 6.2 API 면 안에 가둔다 |
| Performance latency baseline | Numbers measured on a build agent are not a certification | `httpClientPerformanceTest` asserts its structural bounds and the streaming heap bound in every run; it asserts no latency figure | | 성능 지연 기준선 | 빌드 agent에서 잰 숫자는 인증이 아니다 | `httpClientPerformanceTest`가 매번 구조적 상한과 스트리밍 heap 상한을 단언한다. 지연 숫자는 단언하지 않는다 |
+29 -38
View File
@@ -1,22 +1,19 @@
# JPA batch write configuration # JPA batch 쓰기 설정
`HibernateJpaBatchExecutor` is an advanced opt-in. The template does not enable Hibernate batch `HibernateJpaBatchExecutor`는 고급 opt-in이다. 템플릿은 Hibernate batch 쓰기 설정을 전역으로 켜지 않는다. 통계와 문장
write settings globally because statistics and statement reordering add runtime cost even in 재정렬은 bulk 쓰기를 한 번도 하지 않는 애플리케이션에도 런타임 비용을 더하기 때문이다.
applications that never perform bulk writes.
## What the executor owns ## executor가 가지는 것
A `JpaBatchProfile` owns the JDBC batch size for one batch run. Before the first item is written, `JpaBatchProfile`이 batch 실행 한 번의 JDBC batch 크기를 가진다. executor는 첫 항목을 쓰기 전에
the executor applies `profile.jdbcBatchSize()` to the current Hibernate `Session`. The previous `profile.jdbcBatchSize()`를 지금 Hibernate `Session`에 적용한다. 앞 Session 값은 실패한 실행을 포함해 `finally`에서
Session value is restored in `finally`, including failed runs. 되돌린다.
The executor does **not** open a transaction. The application service must enter a executor는 트랜잭션을 열지 **않는다**. 애플리케이션 서비스가 먼저 `TransactionPort.inWrite(...)` 경계에 들어가야 한다.
`TransactionPort.inWrite(...)` boundary first.
## What the application must configure ## 애플리케이션이 설정할 것
If a profile requests insert or update ordering, the matching Hibernate setting must already be profile이 insert나 update 정렬을 요구하면, 맞는 Hibernate 설정이 SessionFactory에 이미 켜져 있어야 한다.
enabled on the SessionFactory:
```yaml ```yaml
spring: spring:
@@ -28,37 +25,31 @@ spring:
generate_statistics: true generate_statistics: true
``` ```
`hibernate.generate_statistics=true` is required because `BatchExecutionResult` reports measured `BatchExecutionResult`가 잰 flush와 prepared statement의 차이를 보고하므로 `hibernate.generate_statistics=true`가 필요하다.
flush and prepared-statement deltas. A disabled statistics registry would turn those values into 통계 registry가 꺼져 있으면 그 값이 그럴듯한 0이 된다.
convincing zeros.
The `HibernateStatisticsCollector` must also receive an instrumented `JdbcBatchCounter`. `HibernateStatisticsCollector`는 계측된 `JdbcBatchCounter`도 받아야 한다. 이 executor에는
`HibernateStatisticsCollector.of(sessionFactory)` is intentionally insufficient for this executor: `HibernateStatisticsCollector.of(sessionFactory)`가 일부러 모자라다. Hibernate 통계는 실제 JDBC batch 실행을 드러내지 않는다.
Hibernate statistics do not expose actual JDBC batch executions.
`hibernate.default_batch_fetch_size` is unrelated to this write executor. It affects association `hibernate.default_batch_fetch_size`는 이 쓰기 executor와 상관없다. 연관 fetch에 영향을 주고, 쿼리·fetch 조정에 속한다.
fetching and belongs to query/fetch tuning instead.
## Entity identifier constraint ## 엔티티 식별자 제약
When `JpaBatchProfile.batchingRequired()` is true, an entity using `JpaBatchProfile.batchingRequired()`가 참이면 `GenerationType.IDENTITY`를 쓰는 엔티티는 `HibernateBatchConfigurationGuard`가
`GenerationType.IDENTITY` is rejected by `HibernateBatchConfigurationGuard`. Hibernate must issue 거부한다. Hibernate는 생성된 식별자를 얻으려고 INSERT마다 바로 실행해야 하므로, JDBC insert batching으로는 그 profile을
each INSERT immediately to obtain the generated identifier, so JDBC insert batching cannot satisfy 채울 수 없다.
that profile.
Prefer a sequence-based identifier when a workload requires insert batching. Keep the sequence insert batching이 필요한 작업에는 sequence 기반 식별자를 쓴다. sequence의 allocation size는 DB 마이그레이션과 맞춰 둔다.
allocation size aligned with the database migration.
## Failure behavior ## 실패 동작
Configuration is checked before the persister receives the first item: 설정은 persister가 첫 항목을 받기 전에 확인한다.
- missing `hibernate.order_inserts=true` when the profile requests insert ordering: fail; - profile이 insert 정렬을 요구하는데 `hibernate.order_inserts=true`가 없다: 실패.
- missing `hibernate.order_updates=true` when the profile requests update ordering: fail; - profile이 update 정렬을 요구하는데 `hibernate.order_updates=true`가 없다: 실패.
- disabled Hibernate statistics: fail; - Hibernate 통계가 꺼져 있다: 실패.
- missing JDBC batch instrumentation: fail; - JDBC batch 계측이 없다: 실패.
- no caller-owned transaction: fail. - 호출자가 가진 트랜잭션이 없다: 실패.
These failures are deliberate. A batch API that silently degrades to one statement per row produces 이 실패는 일부러다. 행마다 문장 하나로 조용히 떨어지는 batch API는 데이터는 맞지만 성능 증거는 거짓이고, 그것은 기동이나
correct data but false performance evidence, which is harder to detect than a startup or invocation 호출 실패보다 알아채기 어렵다.
failure.
+68 -93
View File
@@ -1,117 +1,92 @@
# Entity Mapping Guide # 엔티티 매핑 가이드
Design §10-§13. The rules here exist because each one has a failure mode that is invisible in review 설계서 §10-§13. 여기 있는 규칙마다, 리뷰에서는 보이지 않고 운영에서는 비싼 실패 꼴이 있다.
and expensive in production.
## The domain owns the model ## 모델은 도메인이 가진다
The platform defines no business entity. Table names, column semantics, keys, unique and check 플랫폼은 업무 엔티티를 정의하지 않는다. 테이블 이름, 열의 뜻, 키, unique·check 요구, 연관, cascade 규칙, lock 정책,
requirements, associations, cascade rules, lock policy, and soft-delete policy all belong to the soft-delete 정책은 모두 도메인 모듈의 것이다. `GenericRepository<T, ID>`도 플랫폼 base repository도 없다. generic API
domain module. There is no `GenericRepository<T, ID>` and no platform base repository, because a 하나는 모든 aggregate를 같은 연산으로 몰아넣고, 그러면 한 aggregate의 나중 요구가 모두의 동작을 바꾼다.
single generic API forces every aggregate through the same operations — and one aggregate's later
requirement then changes behaviour for all of them.
## Entities must be proxyable ## 엔티티는 proxy가 될 수 있어야 한다
- Not `final`. Hibernate creates a lazy proxy by generating a subclass; a final entity cannot be - `final`이 아니다. Hibernate는 subclass를 만들어 lazy proxy를 만든다. final 엔티티는 subclass를 만들 수 없으므로 그것으로의
subclassed, so *every* association to it loads eagerly whatever the mapping says. Nothing errors. 연관은 매핑이 뭐라고 하든 *모두* eager로 읽힌다. 아무 오류도 나지 않는다.
- A non-private no-arg constructor. The provider instantiates entities reflectively before - private이 아닌 인자 없는 생성자. provider는 칸을 채우기 전에 reflection으로 엔티티를 만든다.
populating fields.
`EntityMappingCondition` in the testkit enforces both. testkit의 `EntityMappingCondition`이 둘을 강제한다.
## Identifiers ## 식별자
Default to a sequence with an `allocationSize` that matches the migration's `INCREMENT BY`. When 기본은 sequence이고, `allocationSize`는 마이그레이션의 `INCREMENT BY`와 맞춘다. 둘이 다르면 provider가 sequence가 예약하지
they disagree, the provider hands out identifiers the sequence has not reserved and the collision 않은 식별자를 내주고, 충돌은 나중에 부하에서 primary key 위반으로 드러난다.
surfaces later as a primary-key violation under load.
`GenerationType.IDENTITY` is supported and limited: the key is assigned on insert, so the provider `GenerationType.IDENTITY`는 지원하지만 제한이 있다. 키가 insert 때 정해지므로 provider는 키를 알려고 insert마다 바로
must execute each insert immediately to learn it, which disables JDBC insert batching entirely. 실행해야 하고, 그러면 JDBC insert batching이 아예 꺼진다. `HibernateBatchConfigurationGuard`는 IDENTITY 엔티티를 대상으로
`HibernateBatchConfigurationGuard` fails a batch profile that targets an IDENTITY entity rather than 하는 batch profile을, import가 조용히 열 배 느리게 돌게 두는 대신 실패시킨다.
letting the import silently run an order of magnitude slower.
UUIDv7 (`UuidV7Generator`) is the application-side option. It is preferred over UUIDv4 for a primary UUIDv7(`UuidV7Generator`)은 애플리케이션 쪽 선택지다. primary key로는 UUIDv4보다 낫다. v4는 고르게 무작위라서 insert마다
key because v4 is uniformly random: every insert lands on a random leaf of the B-tree, so the index B-tree의 무작위 leaf에 떨어지고, 인덱스가 캐시에 머물지 못하며, 쓰기 증폭이 테이블과 함께 커진다.
never stays in cache and write amplification grows with the table.
## Values ## 값
- Enums are `EnumType.STRING` or an explicit converter. **Never** `ORDINAL` — it stores the - enum은 `EnumType.STRING`이나 명시적 converter다. `ORDINAL`은 **절대** 쓰지 않는다. 상수의 위치를 저장하므로, 끝이 아닌
constant's position, so inserting a new constant anywhere but the end silently reinterprets every 곳에 새 상수를 넣으면 기존 행이 모두 조용히 다른 뜻이 된다.
existing row. - 금액은 정밀도와 scale을 명시한 `BigDecimal`이다. `double`은 `0.1`을 나타내지 못해서 합계가 어긋나고 맞추기가 장부와
- Money is `BigDecimal` with explicit precision and scale. `double` cannot represent `0.1`, so sums 다른 말을 한다.
drift and reconciliation disagrees with the ledger. - `Duration`은 밀리초를 저장하는 converter를 거친다. ISO-8601 문자열 꼴은 SQL에서 정렬과 비교가 틀린다.
- `Duration` goes through a converter that stores milliseconds. The ISO-8601 text form sorts and - `Instant`와 `OffsetDateTime`은 다르게 매핑된다. 한쪽에 맞춘 열은 다른 쪽을 그대로 저장하지 못한다.
compares wrongly in SQL.
- `Instant` and `OffsetDateTime` map differently; a column typed for one cannot faithfully store the
other.
## Associations ## 연관 (Associations)
Map each association from **one side only**. A JPA association between two entities is one foreign 연관은 **한쪽에서만** 매핑한다. 두 엔티티 사이의 JPA 연관은 foreign key 열 하나다. 양방향 짝(자식의 `@ManyToOne`과 부모의
key column. A bidirectional pair (`@ManyToOne` on the child plus `@OneToMany(mappedBy = ...)` on `@OneToMany(mappedBy = ...)`)은 그 열 하나를 Java 칸 둘에 저장하고, JPA는 소유하는 쪽만 쓴다. 짝은 모든 호출자가 두 칸을
the parent) stores that one column in two Java fields, and JPA writes only the owning one. The pair 함께 고치는 것을 기억할 때만 맞고, 누가 잊어도 아무것도 실패하지 않는다.
stays consistent only while every caller remembers to update both fields, and nothing fails when
someone forgets.
What to use, in order of preference: 쓸 것, 고르는 순서대로:
1. **An ID reference between aggregates.** Hold the other aggregate's identifier as a plain column 1. **aggregate 사이에는 ID 참조.** 다른 aggregate의 식별자를 평범한 열로 든다(`UUID ownerId`). 지금 템플릿의 모든 운영 엔티티가
(`UUID ownerId`). This is what every production entity in the template does today. Loading the 이렇게 한다. 다른 aggregate를 읽는 것은 명시적인 repository 호출이라, aggregate를 넘는 읽기가 코드에 보인다.
other aggregate is an explicit repository call, so a cross-aggregate load is visible in the code. 2. **한 aggregate 안에서는 단방향 `@ManyToOne`**, 늘 `fetch = FetchType.LAZY`. JPA의 to-one 기본값은 `EAGER`라서, 자식을
2. **A unidirectional `@ManyToOne` inside one aggregate**, always `fetch = FetchType.LAZY`. JPA's 읽는 모든 쿼리가 부모도 조회한다. JPA 애플리케이션에서 가장 흔한 실수 N+1이다.
default for a to-one association is `EAGER`, so every query that loads a child also queries for 3. **collection은 칸이 아니라 쿼리다.** 「X의 자식들」은 repository 메서드다(`findByParentId`, 또는 SQL에서 페이지를 나누는
its parent — the most common accidental N+1 in a JPA application. fetch join이나 projection 쿼리). 쿼리는 자기 fetch 계획과 페이지를 말하고, 매핑한 collection은 둘 다 숨긴다.
3. **A collection is a query, not a field.** "The children of X" is a repository method 4. **aggregate가 가진 값**(태그 목록, 코드 집합)은 엔티티가 아니라 `@ElementCollection`(`LAZY`)이다.
(`findByParentId`, or a fetch-join or projection query that pages in SQL). The query states its
own fetch plan and page, where a mapped collection hides both.
4. **Values the aggregate owns** — a list of tags, a set of codes — are `@ElementCollection`
(`LAZY`), not entities.
A unidirectional `@OneToMany` with its own `@JoinColumn` is the exception, not the default. Use it 자기 `@JoinColumn`이 있는 단방향 `@OneToMany`는 기본이 아니라 예외다. root가 정말 가지고 root를 통해서만 바꾸는 자식
only for child entities the root genuinely owns and changes only through itself (the testkit's 엔티티에만 쓴다(testkit의 `LifecycleParent`와 `PagedParent`가 이 모양이다). join 열이 nullable이면 자식마다 `UPDATE` 한
`LifecycleParent` and `PagedParent` are this shape). It still costs an `UPDATE` per child when the 번이 들고, collection은 여전히 한 덩어리로 읽힌다. 그러면 자식에는 root로 돌아가는 연관이 없다. 같은 join 열에 읽기 전용
join column is nullable, and the collection still loads as a unit. The child then has no `@ManyToOne`(`insertable = false, updatable = false`)도 두지 않는다. 그것은 이름을 붙이는 `mappedBy`만 없을 뿐 다시 양방향
association back to the root — not even a read-only `@ManyToOne` on the same join column 짝이다. 자식이 root가 필요하면 root의 ID를 든다.
(`insertable = false, updatable = false`): that is the bidirectional pair again, without the
`mappedBy` that names it. If the child needs the root, it holds the root's ID.
`CascadeType.ALL` with `orphanRemoval` is correct only for a child the aggregate genuinely owns. `orphanRemoval`과 함께 쓰는 `CascadeType.ALL`은 aggregate가 정말 가진 자식에만 맞다. 독립된 aggregate 사이에서는 시스템의
Between independent aggregates it deletes rows another part of the system still owns — another 다른 부분이 아직 가진 행을 지운다. 그것들이 ID 참조인 또 하나의 이유다.
reason those are ID references.
`JpaArchitectureRules.associationsAreMappedFromOneSideOnly()` (testkit) fails the build on every `JpaArchitectureRules.associationsAreMappedFromOneSideOnly()`(testkit)는 `@Entity`, `@MappedSuperclass`, `@Embeddable` 타입의
bidirectional pair, on `@Entity`, `@MappedSuperclass` and `@Embeddable` types: an association that 모든 양방향 짝에서 빌드를 실패시킨다. `mappedBy`를 선언한 연관(그 반대쪽 반만 보고한다), 그리고 `mappedBy` 없이 서로를
declares `mappedBy` (only that inverse half is reported), and two entities whose associations point 가리키는 두 엔티티(두 반을 다 보고한다. 위의 `@JoinColumn` 꼴, review RR-03-04)다. 메시지는 짝이 링크를 어떻게 가지는지
at each other without `mappedBy` (both halves are reported — the `@JoinColumn` form above, review 말한다. 양 끝에서 매핑한 join 열 하나이거나, 링크를 두 번 저장한 것이다. 두 번 저장한 것은 자식 자신의 `@ManyToOne` 열 옆
RR-03-04). The message says how the pair keeps the link: one join column mapped from both ends, or join 테이블의, `@JoinColumn` 없는 `@OneToMany`(`mappedBy`를 잊으면 생긴다)이거나, 저마다 join 테이블을 가진 `@ManyToMany`
the link stored twice — a `@OneToMany` without `@JoinColumn` in a join table beside the child's own 둘이다(재확인 리뷰 round 3, RR3-02-05). 그 마지막 검사는 서로에게 저마다 foreign key를 든 두 엔티티도 거부한다
`@ManyToOne` column (what a forgotten `mappedBy` produces), or two `@ManyToMany` each owning a join (`Order.@OneToOne latestInvoice`와 `Invoice.@ManyToOne order`). 링크 하나를 두 번 매핑한 것은 아니고, 메시지도 그렇게
table (re-review round 3, RR3-02-05). That last check also refuses two entities that each hold their own foreign key to the 말한다. 일부러 거부한다. 그러면 두 테이블이 서로를 참조해서, 어느 행도 먼저 넣거나 지울 수 없고, 키 하나는 nullable이어야
other (`Order.@OneToOne latestInvoice` with `Invoice.@ManyToOne order`). It is not one link mapped 하고 두 번째 `UPDATE`로 써야 하며, 엔티티 그래프가 cycle이 된다. 연관은 한쪽에 두고 다른 쪽에는 ID나 쿼리를 준다(재확인
twice, and the message says so; it is refused on purpose, because the two tables then reference each 리뷰 round 2, RR-02-15). 자기 자신에 링크하는 클래스는, 두 번째 멤버가 반대로 가리킬 때만 짝이다(`@ManyToOne parent`와
other: neither row can be inserted or deleted first, one key has to be nullable and written by a `@OneToMany children`). 자기 자신으로의 `@ManyToOne` 링크 둘(manager와 mentor)은 통과한다. 두 키가 모두 한 테이블을 가리켜서
second `UPDATE`, and the entity graph is a cycle. Keep the association on one side and give the other 순서를 정할 두 테이블이 없기 때문이다. 이 규칙은 `JpaProductionArchitectureTest`(app-bootstrap `architectureTest`)가 운영
an ID or a query (re-review round 2, RR-02-15). A class that links to itself is a pair only when a 그래프 전체에 건다. 실패 메시지가 칸 이름과 이 대안들을 알려 준다.
second member points back the other way (`@ManyToOne parent` with `@OneToMany children`); two
`@ManyToOne` links of a class to itself (a manager and a mentor) pass, because both keys point into
the one table and there are no two tables to order. 이 규칙은 `JpaProductionArchitectureTest`(app-bootstrap
`architectureTest`)가 운영 그래프 전체에 건다.
The failure message names the fields and these alternatives.
Chosen and rejected: 고른 것과 버린 것:
| Option | Decision | Why | | 선택지 | 결정 | 이유 |
| --- | --- | --- | | --- | --- | --- |
| One side only (ID reference, unidirectional `@ManyToOne`, collection by query), enforced by ArchUnit | Chosen | The link lives in one field, so there is nothing to keep in step. The rule turns a developer-memory convention into a build failure | | 한쪽만(ID 참조, 단방향 `@ManyToOne`, 쿼리로 읽는 collection), ArchUnit으로 강제 | 고름 | 링크가 칸 하나에 있어서 맞춰 둘 것이 없다. 규칙이 개발자의 기억에 맡긴 관례를 빌드 실패로 바꾼다 |
| Bidirectional with `mappedBy` and an `addChild`/`removeChild` helper that sets both sides | Rejected | The helper is the only thing keeping the two fields in step, and it must be remembered by every caller, every serializer (cycles in `toString`/JSON) and every cascade decision. A missed update leaves a row unlinked or a graph that disagrees with the database, with no error | | `mappedBy`와 양쪽을 다 설정하는 `addChild`/`removeChild` helper를 둔 양방향 | 버림 | 두 칸을 맞춰 두는 것은 helper뿐이고, 모든 호출자, 모든 serializer(`toString`·JSON의 cycle), 모든 cascade 결정이 그것을 기억해야 한다. 고치기를 하나 놓치면 링크 없는 행이나 DB와 다른 그래프가 남고, 오류는 없다 |
| Ban `@OneToMany` entirely | Rejected for now | It also bans a root-owned child collection, which has no second field to forget. Revisit if a real need for child entities that are read or changed on their own appears — that need is a sign they are a separate aggregate | | `@OneToMany`를 아예 금지 | 지금은 버림 | root가 가진 자식 collection도 막는데, 그것에는 잊을 두 번째 칸이 없다. 자식 엔티티를 따로 읽거나 바꿀 실제 필요가 생기면 다시 본다. 그 필요는 그것이 별도 aggregate라는 신호다 |
| Document only | Rejected | A convention the build does not check is invisible where the mapping is written, and the next copy of the template inherits whatever the examples show | | 문서만 | 버림 | 빌드가 확인하지 않는 관례는 매핑을 쓰는 자리에서 보이지 않고, 템플릿의 다음 사본은 예시가 보여 주는 것을 그대로 물려받는다 |
## Entities never leave the transaction ## 엔티티는 트랜잭션 밖으로 나가지 않는다
A controller must not return an entity, or a collection or `Optional` of one. Response serialisation controller는 엔티티를, 또는 엔티티의 collection이나 `Optional`을 돌려주지 않는다. 응답 직렬화는 트랜잭션이 닫힌 뒤에 일어나므로,
happens after the transaction closes, so a lazy association touched by the serialiser either throws serializer가 건드린 lazy 연관은 예외를 던지거나, OSIV가 켜져 있으면(이 플랫폼은 금지한다) view 계층에서 원소마다 쿼리를 낸다.
or — with OSIV on, which this platform forbids — issues a query from the view layer, one per element. `EntityExposureCondition`은 지워진 반환 타입만이 아니라 generic 타입 인자까지 확인한다.
`EntityExposureCondition` checks generic type arguments, not just the erased return type.
+31 -33
View File
@@ -1,45 +1,43 @@
# Experimental Promotion Checklist # Experimental 승격 점검 목록
A reviewer evaluates this checklist. Every technical item, then the ADR. (The 리뷰어가 이 목록을 판정한다. 기술 항목을 모두 본 뒤 ADR을 본다. (이것을 main 코드로 담았던 `ExperimentalPromotionGate`
`ExperimentalPromotionGate` class that encoded it in main code was removed on 2026-09-25; nothing 클래스는 부르는 곳이 없어 2026-09-25에 지웠다.)
called it.)
## Technical evidence ## 기술 증거
- [ ] **Compatibility** — the Stable contract suite passes on the experimental target, twice, on two - [ ] **호환성** — Stable 계약 suite가 experimental 대상에서, 지원하는 patch 릴리스 둘에서, 두 번 통과한다. 한 번의 통과는
supported patch releases. One passing run is a coincidence. 우연이다.
- [ ] **Security** — for tenancy features, cross-tenant read *and* write are both proven impossible, - [ ] **보안** — tenancy 기능이면 다른 테넌트의 읽기 *와* 쓰기가 둘 다 불가능함을 증명한다. native SQL, bulk DML,
including through native SQL, bulk DML, `getReference`, and the second-level cache. A filter `getReference`, second-level cache를 통한 것도 포함한다. 엔티티 쿼리만 덮는 필터는 그중 어느 것도 덮지 않는다.
that covers only entity queries covers none of those. - [ ] **장애** — 연결 재사용이 테넌트 context를 흘리지 않는다. failover가 쓰기 뒤 읽기를 조용히 낡은 replica로 보내지 않는다.
- [ ] **Failure** — connection reuse does not leak tenant context; a failover does not silently route 커밋 모호함 시나리오가 여전히 맞게 동작한다.
a read-after-write to a stale replica; the commit-ambiguity scenarios still behave. - [ ] **마이그레이션** — 테넌트별 마이그레이션은 부분 실패 뒤 이어서 할 수 있고, 속도가 제한된다. 테넌트마다 schema가 하나면
- [ ] **Migration** — per-tenant migration is resumable after a partial failure, and rate-limited. 실행 한 번은 독립 마이그레이션 N개이고, 「실패했다」는 답이 아니다.
With one schema per tenant, a run is N independent migrations and "it failed" is not an answer. - [ ] **성능** — 풀 용량, 부하에서의 replica 지연, 테넌트별 메모리를 어림하지 않고 잰다. 테넌트마다 DB를 두는 방식은 풀
- [ ] **Performance** — pool capacity, replica lag under load, and per-tenant memory are measured, 하나가 아니라 합으로 실패한다.
not estimated. Database-per-tenant fails as a sum, not as an individual pool.
## Decision ## 결정
- [ ] **Reviewed ADR** — recording what is being promised, the operational burden it carries, and - [ ] **검토한 ADR** — 무엇을 약속하는지, 그것이 지우는 운영 부담, 무엇이 생기면 거두는지를 기록한다.
what would cause it to be withdrawn.
The ADR is not a formality. The technical suites establish that something works; the ADR records ADR은 형식이 아니다. 기술 suite는 무언가가 동작함을 세우고, ADR은 플랫폼이 그것을 약속해야 함을 기록한다. 다른 질문이고
that the platform should promise it, which is a different question with a different cost. 비용도 다르다.
## What does not count as evidence ## 증거로 치지 않는 것
- The version being generally available. - 그 버전이 GA라는 사실.
- The feature working in one environment. - 그 기능이 한 환경에서 동작한다는 사실.
- A passing suite that skipped because Docker was unavailable. - Docker가 없어서 건너뛰고 통과한 suite.
- A green lane whose assertions were relaxed to make it pass. - 통과시키려고 단언을 느슨하게 한 초록 lane.
## Outcomes ## 결과
| Decision | Meaning | 결과 이름은 지운 `ExperimentalPromotionGate`가 쓰던 것이고, 지금은 리뷰어가 판정을 적는 말이다.
| 결정 | 뜻 |
|---|---| |---|---|
| `BLOCKED_TECHNICAL` | at least one suite has not passed | | `BLOCKED_TECHNICAL` | 통과하지 않은 suite가 하나 이상 있다 |
| `BLOCKED_MISSING_ADR` | evidence is complete; no reviewed decision exists | | `BLOCKED_MISSING_ADR` | 증거는 다 있고, 검토한 결정이 없다 |
| `ELIGIBLE_FOR_STABLE_REVIEW` | both; Stable review may begin | | `ELIGIBLE_FOR_STABLE_REVIEW` | 둘 다 있다. Stable 리뷰를 시작해도 된다 |
The two blocked states are distinct because they need different work: one needs evidence, the other 막힌 상태 둘을 나누는 이유는 필요한 일이 달라서다. 하나는 증거가, 다른 하나는 결정이 필요하다.
needs a decision.
+26 -34
View File
@@ -1,43 +1,35 @@
# Experimental Support Matrix # Experimental 지원 매트릭스
Experimental code is library code in `dev.caskeleton.adapter.outbound.persistence.experimental`. Experimental 코드는 `dev.caskeleton.adapter.outbound.persistence.experimental`의 라이브러리 코드다. 그것을 조립하는 것도, 켜는
Nothing composes it and no setting turns it on: a deployment that wants one of these creates the 설정도 없다. 이 중 하나를 원하는 배포는 자기 어댑터 코드에서 진입점을 만들고, 그 호출이 opt-in이다. 어느 것도 Stable 조립에
entry point in its own adapter code, and that call is the opt-in. None of it is part of the Stable 들어가지 않고, `JpaModuleBoundaryTest`가 Stable 패키지가 그것에 의존하지 못하게 막는다.
composition, and `JpaModuleBoundaryTest` keeps Stable packages from depending on it.
| Feature | Entry point | Evidence (PostgreSQL lane unless noted) | State | | 기능 | 진입점 | 증거(따로 적지 않으면 PostgreSQL lane) | 상태 |
|---|---|---|---| |---|---|---|---|
| Shared-schema multi-tenancy (column) | `tenant.TenantContext`, `tenant.TenantAwareRepositoryGuard` | `TenantColumnIsolationTest` | Experimental | | 공유 schema multi-tenancy(열) | `tenant.TenantContext`, `tenant.TenantAwareRepositoryGuard` | `TenantColumnIsolationTest` | Experimental |
| PostgreSQL RLS multi-tenancy | `rls.RlsTenantSessionBinder`, `rls.RlsPolicyVerifier` | `RlsIsolationFailureTest` | Experimental | | PostgreSQL RLS multi-tenancy | `rls.RlsTenantSessionBinder`, `rls.RlsPolicyVerifier` | `RlsIsolationFailureTest` | Experimental |
| Schema-per-tenant | `schema.SchemaMultiTenantConnectionProvider`, `schema.SchemaTenantMigrationOrchestrator` | `SchemaTenantMigrationContractTest` | Experimental | | 테넌트마다 schema | `schema.SchemaMultiTenantConnectionProvider`, `schema.SchemaTenantMigrationOrchestrator` | `SchemaTenantMigrationContractTest` | Experimental |
| Database-per-tenant pool budget | `database.TenantDataSourceRegistry`, `database.TenantPoolBudget` | `TenantPoolCapacityContractTest` | Experimental | | 테넌트마다 DB의 풀 예산 | `database.TenantDataSourceRegistry`, `database.TenantPoolBudget` | `TenantPoolCapacityContractTest` | Experimental |
| Consistency-aware read replica | `replica.ConsistencyAwareDataSourceRouter` (you implement `ReplicaLagMonitor`) | `ReadAfterWriteRoutingContractTest` | Experimental | | 일관성을 아는 read replica | `replica.ConsistencyAwareDataSourceRouter`(`ReplicaLagMonitor`는 직접 구현) | `ReadAfterWriteRoutingContractTest` | Experimental |
| Jakarta Persistence 4.0, Hibernate ORM 8, PostgreSQL 19 | none — probes in `.github/workflows/jpa-next.yml` record `NOT_EXECUTABLE` | `Jpa4CompatibilityTest`, `Hibernate8CompatibilityTest`, `PostgreSql19CompatibilityTest` (unit-lane version canaries) | Not executable | | Jakarta Persistence 4.0, Hibernate ORM 8, PostgreSQL 19 | 없음 — `.github/workflows/jpa-next.yml`의 probe가 `NOT_EXECUTABLE`을 기록 | `Jpa4CompatibilityTest`, `Hibernate8CompatibilityTest`, `PostgreSql19CompatibilityTest`(unit lane의 버전 canary) | 실행 불가 |
The `backend.jpa.experimental.*` flags and `ExperimentalFeatureGate` that used to front these were > 이력: 이것들 앞에 있던 `backend.jpa.experimental.*` 스위치와 `ExperimentalFeatureGate`는 2026-09-25에 지웠다. 어떤 코드도
removed on 2026-09-25: no code read the flags from configuration, so setting one did nothing, and > 설정에서 스위치를 읽지 않아서 켜도 아무 일이 없었고, gate는 호출자가 스스로 만든 map만 확인했다.
the gate only checked a map the caller built itself.
## Known constraints ## 알려진 제약
- Tenant context is fail-closed. An unbound tenant in a shared-schema deployment means a query with - 테넌트 context는 닫힌 채 실패한다. 공유 schema 배포에서 테넌트가 묶이지 않으면 테넌트 조건 없는 쿼리가 되고, 모든 테넌트의
no tenant predicate, which returns every tenant's rows. 행을 돌려준다.
- A Hibernate filter is not the security boundary. It does not apply to native SQL, bulk DML, - Hibernate filter는 보안 경계가 아니다. native SQL, bulk DML, `getReference`, second-level cache에 적용되지 않는다.
`getReference`, or the second-level cache. - RLS에는 셋이 모두 필요하다. `ENABLE ROW LEVEL SECURITY`, `FORCE ROW LEVEL SECURITY`(그렇지 않으면 소유자는 자기 정책에서
- RLS requires all three of: `ENABLE ROW LEVEL SECURITY`, `FORCE ROW LEVEL SECURITY` (the owner is 빠진다), `BYPASSRLS` 없는 런타임 역할.
otherwise exempt from its own policies), and a runtime role without `BYPASSRLS`. - 테넌트 묶기는 트랜잭션 로컬이다. 세션 로컬 설정은 연결이 풀로 돌아간 뒤에도 남는다.
- Tenant bindings are transaction-local. A session-local setting survives the connection's return to - `readOnly=true`만으로는 replica로 보내지 않는다. 쓰기 뒤 읽기는 일관성 token이나 primary를 쓴다.
the pool. - replica 지연 증거를 얻을 수 없으면 primary다. 증거가 없다는 것은 최신이라는 증거가 아니다.
- `readOnly=true` never routes to a replica on its own. Read-after-write uses a consistency token or - 테넌트별 풀은 전역으로 제한한다. 적당한 풀을 가진 테넌트 50개는 연결 100개를 허용하는 서버에 대한 연결 500개다.
the primary. - 테넌트 id는 메트릭 태그가 되지 않는다. 테넌트 수는 정의상 상한이 없다.
- Unavailable replica lag evidence means the primary. Absence of evidence is not evidence of
freshness.
- Per-tenant pools are bounded globally. Fifty tenants with a modest pool each is five hundred
connections against a server that permits a hundred.
- Tenant ids never become metric tags. Tenant cardinality is unbounded by definition.
## Lanes never change Stable ## lane은 Stable을 바꾸지 않는다
A compatibility lane publishes nothing and changes no Stable contract. If Hibernate 8 generates 호환성 lane은 아무것도 게시하지 않고 어떤 Stable 계약도 바꾸지 않는다. Hibernate 8이 fetch-pagination gate에 다른 SQL을
different SQL for the fetch-pagination gate, that is a finding about Hibernate 8 — the 7.x gate keeps 만들면 그것은 Hibernate 8에 대한 발견이다. 7.x gate는 7.x가 해야 할 것을 계속 단언한다. 배포가 돌리는 것이 그것이기 때문이다.
asserting what 7.x must do, because that is what deployments run.
+131 -164
View File
@@ -1,198 +1,165 @@
# Migration Guide # 마이그레이션 가이드
Design §31-§32. Flyway owns the schema; Hibernate only validates. 설계서 §31-§32. 스키마는 Flyway가 가지고, Hibernate는 검증만 한다.
## Who may change the schema 이 문서의 절 셋은 코드와 다른 문서가 영어 제목으로 가리킨다. 그래서 그 절 제목에는 영어 이름을 괄호로 함께 둔다:
「누가 스키마를 바꾸나 (Who may change the schema)」, 「잠금 대기에 상한을 둔다 (Bound the lock wait)」,
「동시 인덱스 빌드 (Concurrent index builds)」.
| Environment | Mode | ## 누가 스키마를 바꾸나 (Who may change the schema)
| 환경 | 방식 |
|---|---| |---|---|
| local, test, dev | migrate at startup with the migration credential | | local, test, dev | 마이그레이션 자격 증명으로 기동할 때 migrate한다 |
| staging, prod | deployment-owned migration; the application validates only | | staging, prod | 배포가 가진 마이그레이션. 애플리케이션은 검증만 한다 |
Migrating from inside the application in production means every instance of a rolling deploy races 운영에서 애플리케이션 안에서 migrate하면 rolling deploy의 모든 인스턴스가 같은 스크립트를 적용하려고 경주하고, 진 쪽의
to apply the same script, and the loser's failure is indistinguishable from a real one. 실패는 진짜 실패와 구별되지 않는다.
Whoever runs the migration holds Flyway's PostgreSQL migration lock for the session, not in a 마이그레이션을 돌리는 쪽은 Flyway의 PostgreSQL 마이그레이션 잠금을 트랜잭션이 아니라 세션에 둔다:
transaction: `flyway.postgresql.transactional.lock=false`. Flyway's default (`true`) keeps a `flyway.postgresql.transactional.lock=false`. Flyway의 기본값(`true`)은 실행 전체가 끝날 때까지 트랜잭션을 열어 두고,
transaction open until the whole run ends, and a concurrent index build waits for every transaction 동시 인덱스 빌드는 Flyway 자신의 것을 포함해 자기보다 오래된 모든 트랜잭션을 기다린다. 그러면 배포가 오류도 시간 상한도
older than itself, Flyway's own included — the deploy stops with no error and no time limit 없이 멈춘다(아래 「동시 인덱스 빌드」). 템플릿은 자기가 돌리는 모든 Flyway에 이 값을 둔다. Spring Boot가 기동할 때 만드는
("Concurrent index builds" below). The template sets it for every Flyway it runs: the module Flyway에는 module defaults(`config/module-defaults/persistence-jpa.yml`, `spring.flyway.postgresql.transactional-lock:
defaults (`config/module-defaults/persistence-jpa.yml`, `spring.flyway.postgresql.transactional-lock: false`)가, 스스로 만드는 stream에는 `FlywaySchemaPolicy.configure()`가 그렇게 한다. 서비스 자신의 stream도 거기서
false`) for the one Spring Boot builds at startup, and `FlywaySchemaPolicy.configure()` for every 시작하고, `JpaProductionArchitectureTest`는 다른 방법으로 Flyway를 만드는 운영 코드를 거부한다. `Flyway.configure()`를
stream it builds itself — a service's own stream starts from it too, and `JpaProductionArchitectureTest` 부르거나, 설정을 직접 만드는 것(`new FluentConfiguration()`, `new ClassicConfiguration()`, 그 둘의 subclass,
refuses production code that builds a Flyway any other way: calling `Flyway.configure()`, or `FluentConfiguration::new`)이다. 정책의 설정 위에 `new Flyway(...)`를 하는 것은 허용한다. staging과 prod의 배포 쪽
constructing a configuration itself (`new FluentConfiguration()`, `new ClassicConfiguration()`, a 마이그레이션은 이 저장소 밖에 있다. 그 도구에도 같은 값을 준다(`FLYWAY_POSTGRESQL_TRANSACTIONAL_LOCK=false`, 또는 그 도구
subclass of either, or `FluentConfiguration::new`). `new Flyway(...)` over the policy's configuration 설정 파일의 위 키).
is allowed. The deployment-owned migration of
staging and prod is outside this repository: give its tool the same value
(`FLYWAY_POSTGRESQL_TRANSACTIONAL_LOCK=false`, or the key above in its configuration file).
A session lock assumes the connection Flyway takes stays its own for the whole run, which the 세션 잠금은 Flyway가 잡은 연결이 실행 내내 Flyway의 것으로 남는다고 가정한다. 템플릿의 직접 Hikari 연결이 그것을 준다.
template's direct Hikari connection gives. Behind a pooler in transaction mode (PgBouncer 트랜잭션 모드 pooler(PgBouncer `pool_mode = transaction`) 뒤에서는 unlock이 다른 서버 연결로 가서 아무것도 풀지 못하고,
`pool_mode = transaction`) the unlock can reach another server connection and release nothing, and 다음 마이그레이션은 풀의 연결이 아직 쥔 잠금을 기다린다. 마이그레이션은 직접 연결이나 세션 모드 풀로 돌린다.
the next migration waits for a lock that a pooled connection still holds. Run migrations over a
direct connection or a session-mode pool.
`ddl-auto` is `validate` or `none`. Never `update`: it never drops or narrows anything, so it `ddl-auto`는 `validate`나 `none`이다. `update`는 절대 쓰지 않는다. 그것은 아무것도 지우거나 좁히지 않으므로, 옛 스키마도
produces a schema that is neither the old one nor the one the migrations describe — silently, on 아니고 마이그레이션이 설명하는 스키마도 아닌 스키마를 만든다. 조용히, 먼저 뜬 인스턴스에서.
whichever instance started first.
## Validation fails closed and never repairs ## 검증은 닫힌 채 실패하고, repair하지 않는다
At startup Flyway's own validation (and Hibernate `ddl-auto=validate`) refuses a checksum mismatch, 기동할 때 Flyway 자신의 검증(과 Hibernate `ddl-auto=validate`)이 checksum 불일치, 빠진 마이그레이션, Hibernate가 동의하지
a missing migration, or a schema Hibernate disagrees with. Nothing in the application calls 않는 스키마를 거부한다. 애플리케이션의 어떤 것도 `repair`를 부르지 않는다. 테스트에서는 testkit의 `FlywayValidationGate`가
`repair`. In tests, the testkit's `FlywayValidationGate` turns a failed `ValidateResult` into 실패한 `ValidateResult`를 `SchemaMismatchException`으로 바꾸고, 마이그레이션 계약 테스트가 그것을 쓴다.
`SchemaMismatchException`; the migration contract tests use it.
Repair rewrites the schema history table to match whatever scripts are on disk. That resolves the repair는 schema history 테이블을 디스크에 있는 스크립트에 맞춰 다시 쓴다. 그것은 증거를 지워서 증상을 없앤다. checksum
symptom by deleting the evidence: a checksum mismatch means the deployed script differs from the 불일치는 배포한 스크립트가 적용된 것과 다르다는 뜻이고, 물어야 할 것은 이 DB에 어느 변경이 빠졌느냐다. repair는 그 질문을
applied one, and the interesting question is which change is missing from this database. Repair 물을 수 없게 만든다. repair는 운영자, 이유, 승인이 있는 명시적 관리 작업으로만 있다(설계서 §8.4).
makes that question unaskable. It exists only as an explicit admin operation with an operator, a
reason, and an approval (design §8.4).
The one change to the history an operator makes is narrower than repair: after a concurrent index 운영자가 이력에 하는 변경은 repair보다 좁은 것 하나다. 동시 인덱스 마이그레이션이 실패한 뒤, 그 버전을 다시 돌릴 수 있게
migration fails, the failed row of that one version is deleted so that the version can run again 그 한 버전의 실패 행을 지운다(아래 「동시 인덱스 빌드」). 적용된 행과 그 checksum은 모두 그대로다.
("Concurrent index builds" below). Every applied row, and its checksum, stays as it was.
Only Flyway's structured error codes reach the exception. Its messages embed the script path and 예외에는 Flyway의 구조화된 오류 코드만 닿는다. Flyway의 메시지는 스크립트 경로와 실패한 문장 일부를 담는다.
part of the failing statement.
## Bound the lock wait ## 잠금 대기에 상한을 둔다 (Bound the lock wait)
A migration that locks a table already in use starts with `SET LOCAL lock_timeout = '5s';`, before 이미 쓰는 테이블을 잠그는 마이그레이션은, 잠금을 잡는 첫 문장 전에 `SET LOCAL lock_timeout = '5s';`로 시작한다.
the first statement that takes the lock. `ALTER TABLE` takes the strongest lock there is, which `ALTER TABLE`은 가장 강한 잠금을 잡아 평범한 읽기와도 부딪친다. 동시가 아닌 `CREATE INDEX`는 모든 쓰기를 멈추는 잠금을
conflicts even with a plain read; a non-concurrent `CREATE INDEX` takes one that stops every write; 잡는다. `UPDATE`와 `DELETE`는 다른 트랜잭션이 쥔 행을 기다린다. 상한이 없으면 마이그레이션은 그 테이블을 건드린 가장 오래된
`UPDATE` and `DELETE` wait on the rows other transactions hold. Unbounded, the migration waits for 열린 트랜잭션을 기다린다. psql에서 운영자가 잊은 `BEGIN`에는 마감이 없다. 그사이 도착하는 모든 읽기와 쓰기가 마이그레이션
the oldest open transaction that touched the table — an operator's forgotten `BEGIN` in psql has no 뒤에 줄을 서고, 기다리는 동안 풀 연결을 쥔다. 상한이 있으면 마이그레이션은 5초 뒤 실패하고, Flyway가 통째로 롤백하고, DB는
deadline — and every read and write that arrives meanwhile queues behind the migration, holding a 그 앞 버전에 남고, 새 릴리스는 뜨지 않는다. 장애 대신 실패한 배포다. 그 트랜잭션이 끝난 뒤 다시 배포한다.
pool connection while it waits. With the bound, the migration fails after five seconds, Flyway
rolls it back whole, the database stays on the version before it and the new release does not
start: a failed deploy instead of an outage. Deploy again when the transaction has ended.
`LOCAL`, because a plain `SET` outlives the migration on the pooled connection Flyway borrowed and `LOCAL`인 이유: 평범한 `SET`은 Flyway가 빌린 풀 연결에서 마이그레이션보다 오래 남아, 나중에 그 연결에서 도는 모든 문장을
changes every statement that later runs on it. The value is not zero: `lock_timeout = 0` (or 바꾼다. 값은 0이 아니다. `lock_timeout = 0`(또는 `DEFAULT`, 뒤의 `RESET`)은 상한이 아니다. `executeInTransaction=false`인
`DEFAULT`, or a later `RESET`) is no bound at all. A migration with `executeInTransaction=false` 마이그레이션은 그것을 쓸 수 없다. 트랜잭션 밖의 `SET LOCAL`은 경고만 하기 때문이다. 그래서 테이블을 잠그는 문장은
cannot use it — `SET LOCAL` outside a transaction only warns — so a statement that locks a table 트랜잭션 안에서 도는 마이그레이션에 넣는다. 같은 마이그레이션이 방금 만든 테이블에 대한 문장은 기다릴 것이 없어 상한이
goes into a migration that runs in one. A statement on a table the same migration created a moment 필요 없다. `CREATE TABLE IF NOT EXISTS`는 해당하지 않는다. 테이블이 이미 있을 수 있기 때문이다.
earlier waits for nothing and needs no bound; `CREATE TABLE IF NOT EXISTS` does not count, because
the table may already be there.
Flyway also takes a migration out of its transaction on its own, without a `.sql.conf`: on Flyway는 `.sql.conf` 없이도 스스로 마이그레이션을 트랜잭션 밖으로 뺀다. PostgreSQL 12 이상에서 `VACUUM`, `CREATE [UNIQUE]
PostgreSQL 12 and later, any statement that starts with `VACUUM`, `CREATE [UNIQUE] INDEX INDEX CONCURRENTLY`, `DROP INDEX CONCURRENTLY`, `REINDEX [VERBOSE] SCHEMA|DATABASE|SYSTEM`, `CREATE`나
CONCURRENTLY`, `DROP INDEX CONCURRENTLY`, `REINDEX [VERBOSE] SCHEMA|DATABASE|SYSTEM`, `CREATE` or `DROP DATABASE|TABLESPACE|SUBSCRIPTION`, `ALTER SYSTEM`, `DISCARD ALL`로 시작하는 문장이 있으면 그렇다(Flyway 11,
`DROP DATABASE|TABLESPACE|SUBSCRIPTION`, `ALTER SYSTEM` or `DISCARD ALL` (Flyway 11, `PostgreSQLParser`. 괄호 안의 낱말은 건너뛰므로 `VACUUM (FULL)`과 `REINDEX (VERBOSE) SCHEMA`도 센다). 그런 문장 하나가
`PostgreSQLParser`; words inside parentheses are skipped, so `VACUUM (FULL)` and `REINDEX (VERBOSE) 스크립트 전체를 트랜잭션 밖에 둔다. 다른 문장(`SET LOCAL lock_timeout` 포함) 옆에 두면 Flyway는 기본값 `mixed=false`에서
SCHEMA` count). One such statement puts the whole script outside a transaction. Next to any other 배포 때 그 마이그레이션을 거부한다. `mixed=true`로 둔 서비스는 그것을 돌리지만 상한이 조용히 사라진다. 그런 문장은 따로
statement — a `SET LOCAL lock_timeout` included — Flyway refuses the migration at deploy under its 마이그레이션 하나에 넣는다. `REINDEX TABLE|INDEX CONCURRENTLY`는 Flyway의 목록에 없다. Flyway는 그것을 트랜잭션 안에서
default `mixed=false`; a service that sets `mixed=true` gets it run, with the bound silently gone. 돌리고 PostgreSQL이 거기서 거부하므로 `executeInTransaction=false`가 필요하다(아래). 트랜잭션 안에서 아예 돌 수 없는 잠그는
Put such a statement in a migration of its own. `REINDEX TABLE|INDEX CONCURRENTLY` is not on 문장(`VACUUM FULL`, 동시가 아닌 `REINDEX SCHEMA|DATABASE|SYSTEM`)은 이 방법으로 상한을 둘 수 없고 마이그레이션에 넣지 않는다.
Flyway's list: Flyway runs it in the transaction, PostgreSQL refuses it there, and it needs 배포 밖에서 운영 단계로 손으로 돌린다. 먼저 `SET lock_timeout = '5s';`를 거는 psql 세션에서 한다(세션이 그 단계와 함께
`executeInTransaction=false` (below). A locking statement that cannot run in a transaction at all — 끝나므로 거기서는 평범한 `SET`이 상한이다). `executeInTransaction=true`인 `.sql.conf`도 이것을 바꾸지 못한다. 그 문장과
`VACUUM FULL`, a non-concurrent `REINDEX SCHEMA|DATABASE|SYSTEM` — can never be bounded this way and `SET LOCAL`을 트랜잭션 안에 둘 뿐이고, 배포 때 PostgreSQL이 거부하며, 아래의 inspector도 거부한다.
does not belong in a migration: run it by hand as an operations step, outside a deploy, in a psql
session that sets `SET lock_timeout = '5s';` first (the session ends with the step, so the plain
`SET` is the bound there). A `.sql.conf` with `executeInTransaction=true` does not change that: it
keeps the statement and its `SET LOCAL` in the transaction only for PostgreSQL to refuse it at
deploy, and the inspector below refuses it as well.
Enforced, not remembered: `LockWaitMigrationInspector` (persistence-jpa testkit) reads a script — 기억에 맡기지 않고 강제한다. `LockWaitMigrationInspector`(persistence-jpa testkit)가 스크립트를 읽는다. 옆의 `.sql.conf`도
and the `.sql.conf` beside it, as Flyway reads it (a properties file, `false` in any case), and Flyway처럼 읽고(properties 파일, 대소문자 상관없이 `false`), 그 밖에는 Flyway가 스스로 트랜잭션 밖으로 빼는 문장을 본다.
otherwise the statements Flyway takes out of the transaction on its own — and names the statements 그리고 상한 없이 이미 있는 테이블을 잠그는, 자기 목록의 문장을 이름 댄다: `ALTER TABLE`, `LOCK TABLE`, `TRUNCATE`,
from its list that lock an existing table with no bound in force: `ALTER TABLE`, `LOCK TABLE`, `TRUNCATE`, `DROP TABLE`; `CREATE INDEX`, `DROP TABLE`; `CONCURRENTLY` 없는 `CREATE INDEX`, `DROP INDEX`, `REINDEX`, `REFRESH MATERIALIZED VIEW`, `CLUSTER`,
`DROP INDEX`, `REINDEX` and `REFRESH MATERIALIZED VIEW` without `CONCURRENTLY`, `CLUSTER`, `VACUUM `VACUUM FULL`; 참조하는 테이블에 대한 `REFERENCES`(새 테이블에서도 `ALTER TABLE`에서도. foreign key는 추가되는 동안 부모
FULL`; `REFERENCES` on the table it references, in a new table as much as in an `ALTER TABLE` (a 테이블의 쓰기를 막는다); 그 테이블의 `CREATE TRIGGER`와 `DROP TRIGGER`; `UPDATE`와 `DELETE`. 텍스트를 읽으므로 목록 밖의
foreign key locks its parent against writes while it is added); `CREATE TRIGGER` and `DROP TRIGGER` 문장은 확인하지 않는다. `MigrationLockWaitTest`는 이 leaf의 데이터베이스가 돌리는 모든 트리에 이 검사를 건다. 서비스
on their table; `UPDATE` and `DELETE`. It reads text, so a statement outside the list is not 스트림은 이 테스트를 복사해 자기 폴더를 넣는다. 이 테스트는 Flyway와 같은 방식으로 마이그레이션을 찾고, 소수 버전
checked. `MigrationLockWaitTest`는 이 leaf의 데이터베이스가 돌리는 모든 트리에 이 검사를 건다. 서비스 (`V22_1__`)도 포함한다(`VersionedMigrationFiles`, testkit). 규칙 전에 나간 마이그레이션은 상한 없이 기다리고 그대로 둔다
스트림은 이 테스트를 복사해 자기 폴더를 넣는다. 이 테스트는 Flyway와 같은 방식으로 마이그레이션을 찾고, 소수 (이미 적용됐고, 적용된 파일은 고치지 않는다). 테스트가 그것을 나열하고 새것은 거부한다.
버전(`V22_1__`)도 포함한다(`VersionedMigrationFiles`, testkit). The migrations released before the rule wait unbounded and
stay that way (they are applied, and applied files are never edited); the test lists them and
refuses any new one. `PostgreSqlMigrationLockWaitIntegrationTest`
(`postgresqlMigrationLockWaitIntegrationTest`) shows on real PostgreSQL that a bounded migration
gives up within the bound while another transaction holds the table, and leaves the version below
it; it also compares the inspector's copy of Flyway's list with Flyway itself for the statements it
lists (each is named by the inspector exactly when Flyway refuses it next to a `SET LOCAL`), and
shows a `VACUUM FULL` run under `mixed=true` waiting out a reader despite its `SET LOCAL`. A
statement a Flyway upgrade adds to the list is outside that comparison; `LockWaitMigrationInspectorTest`
pins Flyway's own patterns (`PostgreSQLParser`), so such an upgrade fails the pull request's `ci`
until the copy follows. The gRPC ledger's tree lives in the
optional build, which cannot depend on the testkit: its `GrpcOperationLedgerMigrationLockWaitIT`
runs every ledger migration after V001, read from the tree, against a held ledger instead, so its
next migration is checked on real PostgreSQL. It finds and orders that tree with the testkit's own
`VersionedMigrationFiles`, which the ledger's `build.gradle` copies into its integration-test sources
at build time (`sharedMigrationFileSources`), so both builds read one definition. A concurrent index
build in that tree runs outside a transaction and is no case for a held ledger: it goes in the
test's `RUN_OUTSIDE_A_TRANSACTION` with its reason, and the same test holds each file listed there to
`ConcurrentIndexMigrationInspector`, copied the same way ("Concurrent index builds"). Every ledger
lane applies the tree one file at a time, as Flyway does, so such a file is not refused inside the
implicit transaction of one string holding many. The rule came
from V21 having the bound and V22, in the same commit, not having it (re-review 2026-11-03 round 2,
RR-02-09; round 3, RR3-02-01, RR3-02-03, RR3-02-04; round 4, RR4-02-01; round 6, RR6-03-02,
RR6-03-03; round 7, RR7-03-01).
## Concurrent index builds `PostgreSqlMigrationLockWaitIntegrationTest`(`postgresqlMigrationLockWaitIntegrationTest`)가 실제 PostgreSQL에서 보인다.
다른 트랜잭션이 테이블을 쥔 동안 상한 있는 마이그레이션은 상한 안에 포기하고 그 아래 버전을 남긴다. 또 inspector가 가진
Flyway 목록 사본을 그것이 나열한 문장에 대해 Flyway 자신과 비교하고(inspector는 Flyway가 `SET LOCAL` 옆에서 거부하는 바로
그때 그 문장을 이름 댄다), `mixed=true`에서 돈 `VACUUM FULL`이 `SET LOCAL`에도 불구하고 읽는 쪽을 기다리는 것도 보인다.
Flyway 업그레이드가 목록에 더한 문장은 그 비교 밖이다. `LockWaitMigrationInspectorTest`가 Flyway 자신의 패턴
(`PostgreSQLParser`)을 고정하므로, 그런 업그레이드는 사본이 따라올 때까지 pull request의 `ci`를 실패시킨다.
`CREATE INDEX CONCURRENTLY`, `DROP INDEX CONCURRENTLY` and `REINDEX … CONCURRENTLY` cannot run gRPC ledger의 트리는 optional 빌드에 있어서 testkit에 의존할 수 없다. 그래서 그 `GrpcOperationLedgerMigrationLockWaitIT`가
inside a transaction block. Flyway runs a script outside a transaction on its own when it holds 트리에서 읽은 V001 뒤의 모든 ledger 마이그레이션을 대신 쥔 ledger에 대고 돌리므로, 다음 마이그레이션도 실제 PostgreSQL에서
`CREATE`/`DROP INDEX CONCURRENTLY` or `REINDEX SCHEMA|DATABASE`, with or without `CONCURRENTLY` 확인된다. 그 트리를 찾고 순서를 매기는 것은 testkit 자신의 `VersionedMigrationFiles`다. ledger의 `build.gradle`이 빌드 때
(above). It runs `REINDEX INDEX|TABLE … CONCURRENTLY` — `REINDEX (CONCURRENTLY) TABLE` included — in 그것을 통합 테스트 소스로 복사하므로(`sharedMigrationFileSources`) 두 빌드가 한 정의를 읽는다. 그 트리의 동시 인덱스 빌드는
the transaction, where PostgreSQL refuses it. `PostgreSqlMigrationLockWaitIntegrationTest` shows the 트랜잭션 밖에서 돌므로 쥔 ledger로 시험할 경우가 아니다. 그런 파일은 이유와 함께 테스트의 `RUN_OUTSIDE_A_TRANSACTION`에
five forms on real PostgreSQL. Write the companion configuration for every concurrent statement 넣고, 같은 테스트가 거기 나열한 파일마다 같은 방식으로 복사한 `ConcurrentIndexMigrationInspector`를 건다(「동시 인덱스
anyway, so the file says what it needs and no reader has to know Flyway's list: 빌드」). 모든 ledger lane은 Flyway처럼 트리를 파일 하나씩 적용하므로, 그런 파일이 여러 문장을 담은 문자열 하나의 암묵적
트랜잭션 안에서 거부되지 않는다.
이 규칙은 같은 커밋에서 V21에는 상한이 있고 V22에는 없었던 데서 나왔다(재확인 리뷰 2026-11-03 round 2, RR-02-09; round 3,
RR3-02-01, RR3-02-03, RR3-02-04; round 4, RR4-02-01; round 6, RR6-03-02, RR6-03-03; round 7, RR7-03-01).
## 동시 인덱스 빌드 (Concurrent index builds)
`CREATE INDEX CONCURRENTLY`, `DROP INDEX CONCURRENTLY`, `REINDEX … CONCURRENTLY`는 트랜잭션 블록 안에서 돌 수 없다. Flyway는
스크립트가 `CREATE`/`DROP INDEX CONCURRENTLY`나 `REINDEX SCHEMA|DATABASE`(`CONCURRENTLY`가 있든 없든)를 담으면 스스로
트랜잭션 밖에서 돌린다(위). `REINDEX INDEX|TABLE … CONCURRENTLY`(`REINDEX (CONCURRENTLY) TABLE` 포함)는 트랜잭션 안에서
돌리고, PostgreSQL이 거기서 거부한다. `PostgreSqlMigrationLockWaitIntegrationTest`가 다섯 꼴을 실제 PostgreSQL에서 보인다.
그래도 모든 동시 문장에 짝 설정을 쓴다. 파일이 자기에게 필요한 것을 말하고, 읽는 사람이 Flyway의 목록을 알 필요가 없다.
```conf ```conf
# V42__order_index.sql.conf # V42__order_index.sql.conf
executeInTransaction=false executeInTransaction=false
``` ```
Outside a transaction, `CREATE INDEX CONCURRENTLY` and `REINDEX … CONCURRENTLY` still wait until 트랜잭션 밖에서도 `CREATE INDEX CONCURRENTLY`와 `REINDEX … CONCURRENTLY`는 자기보다 오래된 모든 트랜잭션이 끝날 때까지
every transaction older than them has ended. Under Flyway's default lock that includes the 기다린다. Flyway 기본 잠금에서는 Flyway 자신이 열어 둔 트랜잭션도 거기 들고, Flyway는 다시 빌드를 기다린다. 배포가 끝나지
transaction Flyway itself keeps open, and Flyway waits for the build in turn: the deploy never ends, 않고, 그동안 그 테이블의 다른 DDL과 autovacuum이 빌드 뒤에 줄을 선다. 템플릿의 Flyway는 대신 세션에 잠금을 둔다(「누가
and the table's other DDL and autovacuum queue behind the build meanwhile. The template's Flyway 스키마를 바꾸나」). 그래서 빌드는 다른 트랜잭션만 기다린다. Flyway 기본값에 둔 배포 도구는 그런 첫 마이그레이션에서 멈춘다.
holds its lock for the session instead ("Who may change the schema"), so the build waits only for `DROP INDEX CONCURRENTLY`는 그렇게 기다리지 않는다. 그 테이블에 잠금을 쥔 트랜잭션만 기다린다.
other transactions; a deployment tool left on Flyway's default stops on the first such migration. `PostgreSqlConcurrentIndexMigrationIntegrationTest`(`postgresqlConcurrentIndexMigrationIntegrationTest`)가 두 빌드를 두 번째
`DROP INDEX CONCURRENTLY` does not wait that way: it waits only for the transactions that hold a 배포로, module defaults로 Spring Boot가 만드는 Flyway와 `FlywaySchemaPolicy.configure()`로, 실제 PostgreSQL에 적용한다.
lock on its table. `PostgreSqlConcurrentIndexMigrationIntegrationTest` 다른 트랜잭션은 여전히 센다. 운영자나 리포트가 열어 둔 긴 트랜잭션은 빌드를 붙잡고, 테이블을 건드린 뒤라면 삭제도 붙잡는다.
(`postgresqlConcurrentIndexMigrationIntegrationTest`) applies both builds as a second deploy, with 트랜잭션 밖에서 도는 파일은 그 대기에 `SET LOCAL`로 상한을 둘 수 없다. 그런 마이그레이션을 배포하기 전에 오래된 트랜잭션
the Flyway Spring Boot builds from the module defaults and with `FlywaySchemaPolicy.configure()`, (`pg_stat_activity.xact_start`)을 찾는다.
on real PostgreSQL. The other transactions still count: a long one an operator or a report keeps
open holds the build, and the drop too once it has touched the table, and a file run outside a
transaction cannot bound that wait with `SET LOCAL`. Look for old transactions
(`pg_stat_activity.xact_start`) before deploying one.
The testkit's `ConcurrentIndexMigrationInspector` checks a script for this in a migration test testkit의 `ConcurrentIndexMigrationInspector`가 마이그레이션 테스트에서 스크립트를 이 관점으로 확인하고(기동 때 확인하는
(nothing checks it at startup), and additionally requires the migration to contain nothing else. 것은 없다), 그 마이그레이션에 다른 것이 없기를 더 요구한다. 다른 문장 옆에 두면, 아무것도 설정하지 않았을 때 동시 문장은
Next to another statement, a concurrent one makes Flyway refuse the file before any of it runs when Flyway가 파일을 하나도 돌리기 전에 거부하게 만든다. `executeInTransaction=false`면 Flyway는 문장마다 따로 커밋하고, 실패한
nothing configures it; with `executeInTransaction=false` Flyway commits each statement on its own, 빌드는 그 앞 문장을 적용된 채 남긴다. 손으로 다시 맞춰야 하는 상태다.
and a failed build leaves the statements before it applied — state to reconstruct by hand.
Alone, a failed statement leaves an invalid index and a history row with `success = false` for its 혼자 있는 문장이 실패하면 무효 인덱스와 그 버전의 `success = false` 이력 행을 남기고, 그 행이 사라질 때까지 Flyway는 뒤의
version, and Flyway refuses every later deploy ("Detected failed migration to version …") until that 모든 배포를 거부한다("Detected failed migration to version …"). 인덱스를 지우는 것만으로는 안 된다. 복구는
row is gone: dropping the index is not enough. The recovery is [migration-failed.md](../runbooks/migration-failed.md) 「실패한 동시 인덱스 마이그레이션 복구 (Recover a failed concurrent
[migration-failed.md](../runbooks/migration-failed.md) "Recover a failed concurrent index migration": index migration)」다. 도는 빌드가 없는지 확인하고, 원인을 없애고, 실패한 빌드나 재빌드가 남긴 무효 인덱스를 지우고, 그
confirm no build is running, remove the cause, drop the invalid index a failed build or rebuild 버전의 실패 행만 지우고, 다시 배포한다. 실패한 `DROP INDEX CONCURRENTLY`는 지우던 인덱스를 무효로 남긴다. runbook은 그것을
left, delete that version's failed row and nothing else, deploy again. A failed `DROP INDEX 다시 배포가 지우도록 남긴다. 손으로 지우면 같은 문장이 실패하기 때문이다. 이것은 `flyway repair`가 아니다. repair는 남은 행의
CONCURRENTLY` leaves invalid the index it was dropping; the runbook leaves that one for the deploy checksum도 다시 쓴다. `PostgreSqlConcurrentIndexMigrationIntegrationTest`(`postgresqlConcurrentIndexMigrationIntegrationTest`)가
again to drop, since dropped by hand it makes the same statement fail. It is not `flyway repair`, runbook에서 읽은 runbook의 SQL을, 중복으로 실패한 unique 빌드 뒤와, 열린 트랜잭션을 기다리다 취소된 재빌드와 삭제 뒤에 돌리고,
which would also rewrite the remaining rows' checksums. `PostgreSqlConcurrentIndexMigrationIntegrationTest` 위의 섞인 파일 둘도 보인다.
(`postgresqlConcurrentIndexMigrationIntegrationTest`) runs the runbook's SQL, read from the runbook,
after a unique build that failed on a duplicate and after a rebuild and a drop cancelled while they
waited for an open transaction, and shows both mixed files above.
An invalid index is not merely useless — the planner ignores it while every write still maintains 무효 인덱스는 쓸모없기만 한 게 아니다. planner는 그것을 무시하는데 모든 쓰기는 여전히 그것을 유지한다. 찾는 쿼리는
it. [runbooks.md](runbooks.md) has the query that finds them. Nothing drops them automatically: an [runbooks.md](runbooks.md)에 있다. 아무것도 그것을 자동으로 지우지 않는다. 무효 인덱스는 아직 도는 빌드를 뜻할 수도 있고,
invalid index can also mean a build is still running, and the two are indistinguishable from the 카탈로그만으로는 둘을 구별할 수 없다.
catalog alone.
## Upgrade scenarios ## 업그레이드 시나리오
Three, each catching something the others do not: 셋이고, 저마다 다른 것이 못 잡는 것을 잡는다.
| Scenario | Catches | | 시나리오 | 잡는 것 |
|---|---| |---|---|
| `empty` | an early migration edited to match a later one, no longer applying to a fresh database | | `empty` | 뒤 마이그레이션에 맞추려고 고친 앞 마이그레이션이 새 DB에 더는 적용되지 않음 |
| `previous-release` | the actual deployment path; the only one exercising this release's migrations | | `previous-release` | 실제 배포 경로. 이 릴리스의 마이그레이션을 돌리는 유일한 시나리오 |
| `oldest-supported` | a migration that silently assumes state only recent databases have | | `oldest-supported` | 최근 DB에만 있는 상태를 몰래 가정하는 마이그레이션 |
Each asserts a data invariant, not just the schema version. A migration that renames a column and 시나리오마다 스키마 버전만이 아니라 데이터 불변식을 단언한다. 열 이름을 바꾸면서 내용을 잃은 마이그레이션은 버전은 맞고
loses its contents leaves the version correct and the data gone. 데이터는 사라진 채로 남는다.
+35 -44
View File
@@ -1,58 +1,49 @@
# Observability # 관측
Design §37. What is measured, and what must never appear in a measurement. 설계서 §37. 무엇을 재고, 측정에 무엇이 절대 나타나면 안 되나.
## What is emitted by default ## 기본으로 내는 것
Nothing JPA-specific. No composition constructs a `MeterRegistry`-backed observation for the JPA 고유의 것은 없다. 어떤 조립도 플랫폼에 `MeterRegistry` 기반 observation을 만들지 않고, `SpringTransaction`은 트랜잭션
platform, and `SpringTransaction` records no transaction metric. The `jpa.transaction.*` meters 메트릭을 기록하지 않는다. 트랜잭션 결과는 JPA meter가 아니라 공유 영속성 오류 코드와 애플리케이션 자신의 메트릭으로 보인다.
this page used to list (`duration`, `rollback`, `timeout`, `completion.unknown`) were produced by
`JpaTransactionObservation`, which nothing constructed; it was removed on 2026-09-25
(`docs/capability-status.md`). Transaction outcomes are visible through the shared persistence error
codes and the application's own metrics, not through a JPA meter.
## Query metrics — only when the caller asks > 이력: 이 문서가 전에 적던 `jpa.transaction.*` meter(`duration`, `rollback`, `timeout`, `completion.unknown`)는
> `JpaTransactionObservation`이 만들었는데, 그것을 만드는 곳이 없어서 2026-09-25에 지웠다(`docs/capability-status.md`).
`jpa.query.duration` and `jpa.query.rows` are recorded by `MicrometerQueryObservation`, and only ## 쿼리 메트릭 — 호출자가 요청할 때만
when a service passes it to a library executor that accepts a `QueryObservation`
(`JpaStreamExecutor`, `HibernateBulkDmlExecutor`). The default is `NoopQueryObservation`. Rows are
measured as well as duration because a query that issues one statement and hydrates twenty thousand
rows is fast per statement and catastrophic per request — a duration metric alone reports it as
merely slow.
## Bounded tags, always `jpa.query.duration`과 `jpa.query.rows`는 `MicrometerQueryObservation`이 기록한다. 서비스가 `QueryObservation`을 받는 라이브러리
executor(`JpaStreamExecutor`, `HibernateBulkDmlExecutor`)에 그것을 넘길 때만이다. 기본값은 `NoopQueryObservation`이다. 걸린
시간뿐 아니라 행도 재는 이유가 있다. 문장 하나를 내고 행 2만 개를 채우는 쿼리는 문장으로는 빠르고 요청으로는 재앙이다. 걸린
시간 메트릭만으로는 그저 느리다고 보고된다.
Every meter `MicrometerQueryObservation` records carries exactly five tags: persistence unit, ## 태그는 늘 상한이 있다
operation, query, outcome, failure category (`JpaMetricTags`). All five are registered identifiers,
validated by `LowCardinality` at construction rather than at the registry — so an unbounded value
fails where it was introduced instead of surviving until a dashboard stops loading.
Never a tag: entity id, tenant id, SQL parameter, exception message, JDBC URL. Each is unbounded, so `MicrometerQueryObservation`이 기록하는 meter는 모두 태그를 정확히 다섯 가진다. persistence unit, operation, query, outcome,
each creates a time series per row or per failure; several are also the data the platform keeps out failure category(`JpaMetricTags`)다. 다섯 다 등록된 식별자이고, registry가 아니라 만들 때 `LowCardinality`가 검증한다. 그래서
of logs, which a metrics backend would store just as durably and export just as widely. 상한 없는 값은 대시보드가 안 열릴 때까지 살아남지 않고, 들어온 자리에서 실패한다.
## Query names in SQL 절대 태그가 아닌 것: entity id, tenant id, SQL 파라미터, 예외 메시지, JDBC URL. 하나하나가 상한이 없어서 행마다나 실패마다
시계열을 만든다. 몇은 플랫폼이 로그에서도 빼는 데이터이고, 메트릭 backend는 그것을 로그만큼 오래 저장하고 넓게 내보낸다.
`JpaRepositoryFragmentSupport` sets the registered query name as the `org.hibernate.comment` hint; ## SQL 안의 쿼리 이름
Hibernate writes it into the SQL only when `hibernate.use_sql_comments=true`. The alternative is
`NamedStatementInspector`, which prefixes a statement with the query name bound by
`JpaStreamExecutor`, `JpaKeysetQuerySupport` or `JpaRepositoryFragmentSupport.observing(..)`.
Neither is on by default: a deployment enables the inspector with
`spring.jpa.properties.hibernate.session_factory.statement_inspector=dev.caskeleton.adapter.outbound.persistence.hibernate.NamedStatementInspector`.
The comment then travels into `pg_stat_activity`, `auto_explain`, and the slow-query log. Without it,
"which endpoint issues this query" is answered by grepping the codebase for fragments of SQL.
## Diagnostics `JpaRepositoryFragmentSupport`는 등록한 쿼리 이름을 `org.hibernate.comment` hint로 둔다. Hibernate는
`hibernate.use_sql_comments=true`일 때만 그것을 SQL에 쓴다. 다른 길은 `NamedStatementInspector`다. `JpaStreamExecutor`,
`JpaKeysetQuerySupport`, `JpaRepositoryFragmentSupport.observing(..)`이 묶은 쿼리 이름을 문장 앞에 붙인다. 둘 다 기본으로 꺼져
있다. 배포는
`spring.jpa.properties.hibernate.session_factory.statement_inspector=dev.caskeleton.adapter.outbound.persistence.hibernate.NamedStatementInspector`로
inspector를 켠다. 그러면 주석이 `pg_stat_activity`, `auto_explain`, slow query 로그로 간다. 그것이 없으면 「어느 엔드포인트가 이
쿼리를 내나」는 코드에서 SQL 조각을 grep해서 답한다.
`SqlDiagnosticRedactor.redact(sql)` removes string literals, numbers, and anything email-shaped. It is ## 진단
a utility for code that is about to log SQL; nothing in the platform logs SQL through it. Redaction
is blunt on purpose: preserving "harmless" values would require knowing which columns hold personal
data.
## The actuator endpoint `SqlDiagnosticRedactor.redact(sql)`은 문자열 literal, 숫자, 이메일 모양의 모든 것을 지운다. SQL을 곧 로그에 쓸 코드를 위한
도구다. 플랫폼 안의 어떤 것도 그것을 거쳐 SQL을 로그에 쓰지 않는다. 지우기는 일부러 거칠다. 「해롭지 않은」 값을 남기려면
어느 열이 개인정보를 담는지 알아야 한다.
`jpaplatform` reports database major version, provider version, schema version, OSIV state, runtime ## actuator 엔드포인트
role verification, and capability levels. It reports no JDBC URL, no username, no SQL, and no entity
catalog — an actuator endpoint is reachable by anyone who reaches the management port, and each of `jpaplatform`은 DB major 버전, provider 버전, 스키마 버전, OSIV 상태, 런타임 역할 검증, capability 수준을 보고한다. JDBC URL,
those would be a free reconnaissance answer. It is read-only: an endpoint that could trigger a 사용자 이름, SQL, 엔티티 목록은 보고하지 않는다. actuator 엔드포인트는 management 포트에 닿는 누구나 닿을 수 있고, 그 하나하나가
migration or a repair would be an admin capability exposed over HTTP. 공짜 정찰 답이 된다. 읽기 전용이다. 마이그레이션이나 repair를 일으킬 수 있는 엔드포인트는 HTTP로 드러난 관리 capability가 된다.
+25 -32
View File
@@ -1,50 +1,43 @@
# PostgreSQL Extensions # PostgreSQL 확장 기능
Design §8.3, §21, §30. What the platform uses beyond portable JPA, and what each is guarded by. 설계서 §8.3, §21, §30. 플랫폼이 이식 가능한 JPA 너머에서 무엇을 쓰고, 각각을 무엇이 지키나.
Everything here is core PostgreSQL. No server extension is required. 여기 있는 것은 모두 PostgreSQL core다. 서버 extension은 필요 없다.
## Locking ## 잠금
`SELECT ... FOR UPDATE` with a finite bound, always. `PostgreSqlLockOptions` refuses an unbounded `SELECT ... FOR UPDATE`에는 늘 유한한 상한을 둔다. `PostgreSqlLockOptions`는 상한 없는 잠금 요청을 거부한다. 쥔 쪽이 쥐는 만큼
lock request because it waits as long as the holder holds it, turning one slow transaction into a 기다리므로, 느린 트랜잭션 하나가 막힌 연결 더미가 된다.
pile-up of blocked connections.
`NOWAIT` and a wait timeout are separate requests, not two spellings of one — modelling them as a `NOWAIT`와 대기 시간 상한은 같은 것의 두 표기가 아니라 다른 요청이다. 둘을 마법의 0을 가진 칸 하나로 모델링하면 「기다리지
single field with a magic zero is how "no wait" becomes "wait forever". 않음」이 「영원히 기다림」이 된다.
`55P03` (lock not available) and `40P01` (deadlock) drive opposite recovery and are never collapsed: `55P03`(잠금을 얻을 수 없음)과 `40P01`(교착)은 반대 복구로 이어지므로 합치지 않는다. 앞의 것은 트랜잭션을 살려 두고 호출자에게
the first leaves the transaction alive and the caller in control; the second has already been rolled 통제를 남긴다. 뒤의 것은 서버가 이미 롤백했다.
back by the server.
## JSONB ## JSONB
`JsonDocument` carries a schema name and version alongside the payload. A JSONB column is schemaless `JsonDocument`는 payload와 함께 schema 이름과 버전을 싣는다. JSONB 열은 DB 수준에서 schema가 없으므로, envelope가 없으면 저장된
at the database level, so without an envelope the only record of what a stored document means is the 문서가 무엇을 뜻하는지 기록한 것은 그것을 쓴 코드뿐이다. 두 릴리스 전에 쓴 문서와 지금 문서를 구별할 수 없다.
code that wrote it — and a document written two releases ago is indistinguishable from a current one.
The payload never carries a Java class name. Type metadata in a JSONB column is a deserialization payload에는 Java 클래스 이름을 절대 싣지 않는다. JSONB 열의 타입 메타데이터는 deserialization gadget이다. 행을 쓸 수 있는 누구나
gadget: whoever can write a row chooses the class the reader instantiates. 읽는 쪽이 만들 클래스를 고른다.
Query paths are registered. A JSON path is part of the SQL text and cannot be bound, so forwarding a 쿼리 경로는 등록한다. JSON 경로는 SQL 문장의 일부라 묶을 수 없으므로, 요청 칸을 그것에 넘기면 믿을 수 없는 입력을 문장에 이어
request field into one is concatenating untrusted input into a statement. Values are always bound. 붙이는 것이다. 값은 늘 묶는다.
## Arrays and ranges ## 배열과 범위
Arrays are built with `Connection.createArrayOf`, never by formatting a literal — hand-formatting is 배열은 literal을 꾸미지 않고 `Connection.createArrayOf`로 만든다. 손으로 꾸미면 quoting 버그가 생기고, 쉼표가 든 태그는 배열의
where quoting bugs live, and a tag containing a comma changes the array's shape rather than its 내용이 아니라 모양을 바꾼다.
content.
`PgRange` models both endpoints as independently optional and independently inclusive, because that `PgRange`는 두 끝을 저마다 선택적으로, 저마다 포함 여부를 따로 모델링한다. PostgreSQL range가 그렇기 때문이다.
is what a PostgreSQL range is. Whether `[09:00, 10:00)` and `[10:00, 11:00)` overlap depends on the `[09:00, 10:00)`과 `[10:00, 11:00)`이 겹치는지는 값이 아니라 괄호가 정하고, `timestamptz` 열 한 쌍으로는 그것을 나타낼 수 없다.
bracket, not the values, and a pair of `timestamptz` columns cannot express it.
## COPY (J4 admin) ## COPY (J4 admin)
`COPY` bypasses the Persistence Context, entity callbacks, version checks, and Envers entirely. That `COPY`는 Persistence Context, 엔티티 callback, 버전 확인, Envers를 모두 건너뛴다. 그래서 빠르고, 그래서 관리 capability다. 등록한
is why it is fast and why it is an admin capability with a registered statement, a bounded stream, a 문장, 상한 있는 stream, 행·바이트 상한, 유한한 서버 쪽 `statement_timeout`, 이름 있는 운영자가 필요하다.
row and byte cap, a finite server-side `statement_timeout`, and a named operator.
The registry accepts only `COPY ... FROM STDIN`. `COPY ... FROM '/path'` reads a file on the registry는 `COPY ... FROM STDIN`만 받는다. `COPY ... FROM '/path'`는 *DB 서버*의 파일을 서버 OS 사용자로 읽는다. 바로 그
*database server* as the server's OS user; it is superuser-only for exactly that reason and does not 이유로 superuser 전용이고, 애플리케이션 API 뒤에 둘 것이 아니다.
belong behind an application API.
+41 -53
View File
@@ -1,75 +1,63 @@
# Query and Fetch Guide # 쿼리와 fetch 가이드
Design §23-§28. How queries are chosen, bounded, and proven. 설계서 §23-§28. 쿼리를 어떻게 고르고, 제한하고, 증명하나.
## Named queries ## 이름 있는 쿼리
Every registered query carries a `QueryName`. It is the tag `MicrometerQueryObservation` records 등록한 쿼리는 모두 `QueryName`을 가진다. 그것은 `MicrometerQueryObservation`이 기록하는 태그이고, `pg_stat_activity`와
under and the SQL comment that appears in `pg_stat_activity` and the slow-query log — which is the slow query 로그에 나타나는 SQL 주석이다. 서버의 문장을 그것을 낸 use case와 잇는 것은 그것뿐이다. 둘 다 기본으로 꺼져
only thing that connects a statement on the server back to the use case that issued it. Neither is on 있다. 배포가 각각을 켜는 법은 [observability.md](observability.md)에 있다. 형식이 원본 SQL을 거부하는 데는 이유가 있다. 쿼리
by default; [observability.md](observability.md) says how a deployment turns each on. The format rejects raw 문자열로 만든 메트릭 태그는 처음부터 상한이 없고, 파라미터 값으로 만든 것은 행 데이터를 원격 측정으로 흘린다.
SQL for a reason: a metric tag built from a query string is unbounded by construction, and one built
from a parameterised value leaks row data into telemetry.
## Fetch plans, not eager mappings ## eager 매핑이 아니라 fetch 계획
N+1 is solved per use case with a registered entity graph, not by making an association `EAGER` in N+1은 매핑에서 연관을 `EAGER`로 만들어서가 아니라 use case마다 등록한 entity graph로 푼다. eager 고침은 그것이 필요했던 쿼리
the mapping. The eager fix repairs the one query that needed it and imposes the extra join on every 하나를 고치고, 그 엔티티에 대한 다른 모든 쿼리에 추가 join을 지운다. id만 원했던 쿼리까지.
other query against that entity, including the ones that only wanted the id.
`fetchgraph` and `loadgraph` are different: a fetch graph is exhaustive (attributes outside it are `fetchgraph`와 `loadgraph`는 다르다. fetch graph는 빠짐없는 목록이고(그 밖의 속성은 매핑이 뭐라고 하든 lazy다), load graph는
lazy whatever the mapping says), a load graph is additive. Choosing the wrong one produces either 더하는 것이다. 잘못 고르면 데이터가 빠지거나, graph가 피하려던 증폭이 생긴다.
missing data or the amplification the graph was meant to avoid.
## Measuring, not guessing ## 짐작하지 말고 잰다
`QueryMeasurement` records statements, hydrated entities, rows, fetches, and elapsed time. Statement `QueryMeasurement`는 문장, 채운 엔티티, 행, fetch, 걸린 시간을 기록한다. 문장 수만으로는 중요한 두 실패를 가릴 수 없다.
count alone cannot distinguish the two failures that matter:
- **N+1** — many statements, few rows. - **N+1** — 문장은 많고 행은 적다.
- **Cartesian fetch** — one statement, an enormous number of rows. - **Cartesian fetch** — 문장은 하나이고 행은 엄청나게 많다.
A suite asserting only on statement count passes the second one every time. 문장 수만 단언하는 suite는 두 번째를 늘 통과시킨다.
## Pagination ## 페이지 나누기
Offset pagination makes the database walk and discard `n` rows before returning any. Keyset offset 페이지 나누기는 DB가 무엇이든 돌려주기 전에 `n`행을 지나가며 버리게 한다. keyset 페이지 나누기가 그것을 대신한다.
pagination replaces it:
- The predicate is lexicographic. For an ordering of `(createdAt, id)`, "after `(t, x)`" is - 조건은 사전순이다. `(createdAt, id)` 정렬에서 「`(t, x)` 다음」은 `createdAt < t OR (createdAt = t AND id < x)`다.
`createdAt < t OR (createdAt = t AND id < x)` — **not** `createdAt <= t AND id < x`, which reads `createdAt <= t AND id < x`가 **아니다.** 그것은 그럴듯해 보이지만 결과 중간의 행을 조용히 빠뜨린다.
plausibly and silently drops rows from the middle of the result set. - 정렬은 unique 열로 끝나야 한다. 그렇지 않으면 같은 값이 이어지는 구간 안의 페이지 경계가 행을 중복하고 건너뛴다.
- The ordering must end in a unique column. Without one, a page boundary inside a run of equal - `size + 1`행을 읽고 `size`를 돌려준다. 그 한 행이 count 쿼리 없이 `hasNext`에 답한다. count 쿼리는 두 번째 전체 scan이고,
values duplicates and skips rows. 답이 도착할 때 이미 낡았다.
- `size + 1` rows are fetched and `size` returned. That extra row answers `hasNext` without a count
query, which would be a second full scan whose answer is stale on arrival.
Cursors are signed. An unsigned cursor is client-controlled ordering state: rewriting it lets a cursor에는 서명한다. 서명 없는 cursor는 클라이언트가 다루는 정렬 상태다. 그것을 고치면 호출자가 아무 키로나 건너뛸 수 있다.
caller seek to arbitrary keys.
## Sorting ## 정렬
Client sort parameters are mapped through `SafeSortRegistry`, never passed through. A sort field 클라이언트의 정렬 파라미터는 그대로 넘기지 않고 `SafeSortRegistry`로 매핑한다. 정렬 칸은 묶은 값이 아니라 ORDER BY 절의
reaches the query as part of the ORDER BY clause rather than as a bound value, so forwarding the 일부로 쿼리에 닿으므로, 클라이언트의 문자열을 넘기면 클라이언트가 문장의 일부를 쓰게 된다. `JpaSort.unsafe`는 이 플랫폼에서
client's string means the client writes part of the statement. `JpaSort.unsafe` has no call site in 부르는 곳이 없다.
this platform.
The registry's tie-breaker is always appended, because a sort that does not end in a unique column registry의 tie-breaker는 늘 덧붙인다. unique 열로 끝나지 않는 정렬은 전체 순서가 없고, 전체 순서가 아닌 것으로 페이지를
has no total order and paging over a non-total order duplicates and skips rows. 나누면 행이 중복되고 건너뛰어진다.
## Streaming ## streaming
A JPA `Stream` is a live cursor holding a `ResultSet`, a statement, and a connection. `JpaStreamExecutor` JPA `Stream`은 `ResultSet`, 문장, 연결을 쥔 살아 있는 cursor다. `JpaStreamExecutor`는 그것을 try-with-resources 안에서 다 쓰고
consumes it inside a try-with-resources and never returns it, because a stream returned past the 절대 돌려주지 않는다. 트랜잭션 경계 밖으로 돌려준 stream은 연결 누수이고, 다른 곳의 상관없어 보이는 시간 초과로 나타난다.
transaction boundary is a connection leak that presents as unrelated timeouts elsewhere. A read-only 읽기 전용 트랜잭션이 필요하다. 쓰기 트랜잭션 안의 streaming은 순회 내내 쓰기 연결을 붙잡는다.
transaction is required: streaming inside a write transaction pins a write connection for the whole
traversal.
## Batching ## batching
Configuring `hibernate.jdbc.batch_size` proves nothing. `BatchExecutionResult.jdbcBatches` comes from `hibernate.jdbc.batch_size`를 설정한 것은 아무것도 증명하지 않는다. `BatchExecutionResult.jdbcBatches`는 JDBC 층에서 실제
counting real `executeBatch()` calls at the JDBC layer, because an IDENTITY generator, an interleaved `executeBatch()` 호출을 세서 나온다. IDENTITY generator, 끼어든 select, 반복 중간의 flush는 설정이 켜져 있다고 말하는 동안
select, or a mid-loop flush disables batching while the configuration still says it is on. batching을 꺼 버리기 때문이다.
Flush and clear are separate boundaries. Flushing alone sends the statements and keeps every entity flush와 clear는 다른 경계다. flush만 하면 문장은 보내지만 모든 엔티티를 Persistence Context에 남긴다. 대량 import의 전형적인
in the Persistence Context — the classic bulk-import out-of-memory. 메모리 부족이다.
+102 -120
View File
@@ -1,165 +1,147 @@
# JPA Relational Persistence Platform — Repository Adaptation Contract # JPA 관계형 영속성 플랫폼 — 저장소 대응 계약
**Design source:** `docs/design/2026-08-11-jpa-persistence-platform-design.md` **설계 출처:** `docs/design/2026-08-11-jpa-persistence-platform-design.md`
**Stable plan source:** `docs/history/plans/2026-08-11-jpa-persistence-platform-implementation-plan.md` **Stable 계획 출처:** `docs/history/plans/2026-08-11-jpa-persistence-platform-implementation-plan.md`
**Experimental plan source:** `docs/history/plans/2026-08-11-jpa-persistence-experimental-expansion-plan.md` **Experimental 계획 출처:** `docs/history/plans/2026-08-11-jpa-persistence-experimental-expansion-plan.md`
The design package states its own adaptation rule (§3.2): the assumed package paths and Gradle 설계 패키지는 자기 대응 규칙을 스스로 밝힌다(§3.2). 가정한 패키지 경로와 Gradle 구조는 실제 Backend Skeleton 저장소를
structure are explicit implementation *assumptions* made because the real Backend Skeleton 받지 못해서 둔 명시적 구현 *가정*이다. 구현 전에 공개 계약과 정책 의미는 지키면서 경로를 저장소의 기존 관례와 root 패키지에
repository was not supplied. Before implementing, paths are adjusted to the repository's existing 맞춘다.
conventions and root package while the public contracts and policy semantics are preserved.
This file is the single record of *how* that mapping was performed. Only paths, build DSL, and 이 파일은 그 대응을 *어떻게* 했는지 적는 유일한 기록이다. 바뀐 것은 경로, 빌드 DSL, 조립 루트 소유뿐이다. 공개 계약, 정책
composition-root ownership changed. Public contracts, policy order, retry semantics, and error 순서, 재시도 의미, 오류 의미는 명세대로 구현했다.
semantics are implemented as specified.
## 1. Why the module layout differs ## 1. 모듈 배치가 다른 이유
The plan assumes a greenfield library with 18 Stable Gradle projects under `modules/jpa/` plus 7 계획은 `modules/jpa/` 아래 Stable Gradle 프로젝트 18개와 `modules/jpa-experimental/` 아래 Experimental 프로젝트 7개를 둔
Experimental projects under `modules/jpa-experimental/`. This repository is a Clean Architecture 새 라이브러리를 가정한다. 이 저장소는 **fail-closed registry**(`src/config/architecture/modules.json`)를 가진 Clean
template whose **fail-closed registry** (`src/config/architecture/modules.json`, enforced by Architecture 템플릿이다. `src/settings.gradle`은 registry를 읽고 검증한 뒤 등록된 프로젝트만 들이고,
`src/settings.gradle` and `verifyCleanArchitectureDependencies`) declares **exactly 19 leaf `verifyCleanArchitectureDependencies`가 그 밖의 edge를 막는다. leaf 목록은 registry가 정한다. 계획의 Gradle 프로젝트를
identities**, and `src/settings.gradle` throws when the registry does not contain exactly 19 새로 만들면 `AGENTS.md`의 HARD-STOP #5를 어긴다.
modules. Creating 25 more Gradle projects would violate HARD-STOP #5 in `AGENTS.md`.
Therefore the plan's library modules become **package boundaries inside the registered leaf** 그래서 계획의 라이브러리 모듈은 등록 leaf `:adapter:outbound:persistence-jpa` **안의 패키지 경계**가 된다. 예외는 이 저장소
`:adapter:outbound:persistence-jpa`, with two exceptions driven by this repository's own rules. 자신의 규칙에서 나온 둘이다. HTTP 클라이언트 플랫폼에 이미 한 것과 같은 대응이다(`docs/httpclient/repository-adaptation.md`).
This is the same adaptation already applied to the HTTP client platform
(`docs/httpclient/repository-adaptation.md`).
| Plan module | Repository home | Reason | | 계획 모듈 | 저장소 위치 | 이유 |
|---|---|---| |---|---|---|
| `jpa-spring-boot-starter` | `:adapter:outbound:persistence-jpa` (`…persistence.autoconfigure`, `…persistence.startup`) | Relational persistence is a capability module selected by one build line (`AGENTS.md` capability rules): the leaf registers its own auto-configuration, startup validation, actuator view and shipped settings, and the default composition does not carry it. Use-case assembly over its ports (the outbox relay) stays in `app-bootstrap`. | | `jpa-spring-boot-starter` | `:adapter:outbound:persistence-jpa` (`…persistence.autoconfigure`, `…persistence.startup`) | 관계형 영속성은 빌드 한 줄로 고르는 capability 모듈이다(`AGENTS.md` capability 규칙). leaf가 자기 auto-configuration, 기동 검증, actuator view, 내보내는 설정을 등록하고, 기본 조립은 그것을 싣지 않는다. 그 port 위의 use case 조립(outbox relay)은 `composition:outbox-relay`에 있다. |
| `jpa-testkit`, `jpa-testkit-postgresql`, `jpa-testkit-migration`, `jpa-testkit-queryplan` | `:adapter:outbound:persistence-jpa` `src/testkit/java/**/testkit` | The plan forbids production modules depending on the testkit. A source set whose dependencies are declared only on test configurations gives the same guarantee without a new Gradle project, and more than one lane consumes it. | | `jpa-testkit`, `jpa-testkit-postgresql`, `jpa-testkit-migration`, `jpa-testkit-queryplan` | `:adapter:outbound:persistence-jpa` `src/testFixtures/java/**/testkit` | 계획은 운영 모듈이 testkit에 의존하는 것을 막는다. 의존을 test 설정에만 선언한 source set이 새 Gradle 프로젝트 없이 같은 보장을 주고, 여러 lane이 그것을 쓴다. |
The package boundary is enforced by `JpaModuleBoundaryTest`. It holds a closed catalog of the 패키지 경계는 `JpaModuleBoundaryTest`가 강제한다. 운영 root의 바로 아래 자식 패키지를 닫힌 목록으로 들고, 그 목록을
production root's direct child packages, compares that catalog against the tree for exact equality, 트리와 정확히 같은지 비교하고, 관찰한 최상위 edge를 모두 선언한 것과 대조하고, cycle을 거부한다.
checks every observed top-level edge against the declared ones, and rejects cycles.
This used to be a stronger claim than the test. The catalog listed thirteen packages while the tree > 이력: 전에는 문서의 주장이 테스트보다 강했다. 목록은 패키지 13개였는데 트리에는 22개가 있어서, 아홉 개(`audit`,
held twenty-two, so nine — `audit`, `config`, `failure`, `fileserver`, `h2`, `idempotency`, `lock`, > `config`, `failure`, `fileserver`, `h2`, `idempotency`, `lock`, `notification`, `outbox`)를 아무것도 다스리지 않았고
`notification`, `outbox` — were governed by nothing, and a `transaction → postgresql` / > `transaction → postgresql` / `postgresql → transaction` cycle이 통과했다. 둘 다 닫았다. 새 패키지가 빠져서 초록이 되지
`postgresql → transaction` cycle passed. Both are closed now, and the catalog's exact-equality check > 않게 막는 것은 목록의 정확히-같음 검사다.
is what keeps a new package from being green by omission.
**Known gap.** The catalog governs top-level packages. Sub-package edges inside one top-level **알려진 빈틈.** 목록은 최상위 패키지를 다스린다. 한 최상위 패키지 안의 하위 패키지 edge는 확인하지 않는다. 리뷰
package are not checked, and the target tree in the review's JPA-023 (a `capability/*` layout) is JPA-023의 목표 트리(`capability/*` 배치)는 구현하지 않았다. 알림 설정 facade가 그쪽으로 가는 첫걸음이다.
not implemented — the notification configuration facade is the first step toward it.
## 2. Package mapping ## 2. 패키지 대응
Root package: `io.backend.skeleton.jpa` → `dev.caskeleton.adapter.outbound.persistence`. root 패키지: `io.backend.skeleton.jpa` → `dev.caskeleton.adapter.outbound.persistence`.
| Plan module | Plan package | Repository package | | 계획 모듈 | 계획 패키지 | 저장소 패키지 |
|---|---|---| |---|---|---|
| `jpa-core-api` | `…jpa.api` (+ `.capability`, `.error`, `.query`, `.transaction`) | `dev.caskeleton.adapter.outbound.persistence.api` (+ same subpackages) | | `jpa-core-api` | `…jpa.api` (+ `.capability`, `.error`, `.query`, `.transaction`) | `dev.caskeleton.adapter.outbound.persistence.api` (+ 같은 하위 패키지) |
| `jpa-transaction` | `…jpa.transaction` | `…persistence.transaction` | | `jpa-transaction` | `…jpa.transaction` | `…persistence.transaction` |
| `jpa-spring-data` | `…jpa.springdata` | `…persistence.springdata` | | `jpa-spring-data` | `…jpa.springdata` | `…persistence.springdata` |
| `jpa-querydsl` | `…jpa.querydsl` | `…persistence.querydsl` | | `jpa-querydsl` | `…jpa.querydsl` | `…persistence.querydsl` |
| `jpa-hibernate` | `…jpa.hibernate` (+ `.batch`, `.bulk`, `.stateless`) | `…persistence.hibernate` (+ same subpackages) | | `jpa-hibernate` | `…jpa.hibernate` (+ `.batch`, `.bulk`, `.stateless`) | `…persistence.hibernate` (+ 같은 하위 패키지) |
| `jpa-postgresql` | `…jpa.postgresql` (+ `.error`, `.lock`, `.constraint`, `.json`, `.array`, `.range`, `.write`) | `…persistence.postgresql` (+ same subpackages except `.write`, removed 2026-09-25) | | `jpa-postgresql` | `…jpa.postgresql` (+ `.error`, `.lock`, `.constraint`, `.json`, `.array`, `.range`, `.write`) | `…persistence.postgresql` (+ `.write`를 뺀 같은 하위 패키지. `.write`는 2026-09-25에 지움) |
| `jpa-postgresql-copy` | `…jpa.postgresql.copy` | `…persistence.postgresql.copy` | | `jpa-postgresql-copy` | `…jpa.postgresql.copy` | `…persistence.postgresql.copy` |
| `jpa-migration-flyway` | `…jpa.migration` | `…persistence.migration` | | `jpa-migration-flyway` | `…jpa.migration` | `…persistence.migration` |
| `jpa-auditing` | `…jpa.auditing` | none — removed; `…persistence.audit.AuditableEntity` is the one audit mechanism | | `jpa-auditing` | `…jpa.auditing` | 없음 — 지웠다. `…persistence.audit.AuditableEntity`가 유일한 감사 방식이다 |
| `jpa-envers` | `…jpa.envers` | `…persistence.envers` | | `jpa-envers` | `…jpa.envers` | `…persistence.envers` |
| `jpa-cache-hibernate` | `…jpa.cache` | `…persistence.cache` | | `jpa-cache-hibernate` | `…jpa.cache` | `…persistence.cache` |
| `jpa-observability` | `…jpa.observation` | `…persistence.observation` | | `jpa-observability` | `…jpa.observation` | `…persistence.observation` |
| `jpa-security` | `…jpa.security` | `…persistence.security` | | `jpa-security` | `…jpa.security` | `…persistence.security` |
| `jpa-spring-boot-starter` | `…jpa.autoconfigure` | `…persistence.autoconfigure`, `…persistence.startup` | | `jpa-spring-boot-starter` | `…jpa.autoconfigure` | `…persistence.autoconfigure`, `…persistence.startup` |
| `jpa-testkit*` | `…jpa.testkit` (+ `.id`, `.mapping`, `.lifecycle`, `.query`, `.fetch`, `.postgresql`, `.migration`, `.queryplan`, `.failure`, `.pool`, `.release`) | `…persistence.testkit` (+ same subpackages), `testkit` source set | | `jpa-testkit*` | `…jpa.testkit` (+ `.id`, `.mapping`, `.lifecycle`, `.query`, `.fetch`, `.postgresql`, `.migration`, `.queryplan`, `.failure`, `.pool`, `.release`) | `…persistence.testkit` (+ 같은 하위 패키지), `testFixtures` source set |
| `jpa-experimental/*` | `…jpa.experimental` (+ `.tenant`, `.rls`, `.schema`, `.database`, `.replica`, `.next`) | `…persistence.experimental` (+ same subpackages except `.next`, removed 2026-09-25) | | `jpa-experimental/*` | `…jpa.experimental` (+ `.tenant`, `.rls`, `.schema`, `.database`, `.replica`, `.next`) | `…persistence.experimental` (+ `.next`를 뺀 같은 하위 패키지. `.next`는 2026-09-25에 지움) |
The existing `…persistence.transaction` and `…persistence.postgresql` packages already hold this 이미 있던 `…persistence.transaction`과 `…persistence.postgresql` 패키지는 이 leaf의 `TransactionPort` 구현과 PostgreSQL
leaf's `TransactionPort` implementation and PostgreSQL vendor composition. The platform types are vendor 조립을 이미 가지고 있다. 플랫폼 타입은 **더하기만** 했다. 이름을 바꾸거나 옮기거나 대신한 기존 타입은 없고, 기존
**additive**: no existing type was renamed, moved, or replaced, and no plan type collides with an 이름과 부딪치는 계획 타입도 없다.
existing name.
## 3. Test-suite mapping ## 3. 테스트 suite 대응
The plan declares seven JVM test suites (`test`, `integrationTest`, `contractTest`, 계획은 JVM 테스트 suite 일곱을 선언한다(`test`, `integrationTest`, `contractTest`, `migrationTest`, `failureTest`,
`migrationTest`, `failureTest`, `performanceTest`, `compatibilityTest`). This leaf already owns a `performanceTest`, `compatibilityTest`). 이 leaf는 이미 Docker를 쓰는 `postgresqlIntegrationTest` source set을 가지고,
Docker-backed `postgresqlIntegrationTest` source set and its readiness Gradle tasks are registered 그 readiness Gradle 태스크는 이 leaf의 `build.gradle`에 strict lane으로 등록돼 있다. `JpaReadinessRegistryTest`가 readiness
as strict lanes in this leaf's `build.gradle`; `JpaReadinessRegistryTest` holds the readiness cards card를 그 lane과 대조한다(build-tools의 `verifyJpaReadinessRegistry`를 대신했다).
to those lanes (it replaced the build-tools `verifyJpaReadinessRegistry`).
| Plan suite | Repository lane | | 계획 suite | 저장소 lane |
|---|---| |---|---|
| `test` | `src/test` — hermetic unit lane, `./gradlew :adapter:outbound:persistence-jpa:test` | | `test` | `src/test` — 밀폐된 unit lane, `./gradlew :adapter:outbound:persistence-jpa:test` |
| `contractTest`, `integrationTest`, `migrationTest`, `failureTest`, `compatibilityTest` | `src/postgresqlIntegrationTest` — real PostgreSQL containers; selected by the `jpaPlatform*` Gradle tasks | | `contractTest`, `integrationTest`, `migrationTest`, `failureTest`, `compatibilityTest` | `src/postgresqlIntegrationTest` — 실제 PostgreSQL 컨테이너. `jpaPlatform*` Gradle 태스크가 고른다 |
| `performanceTest` | `src/jpaPlatformPerformanceTest` — pool and `REQUIRES_NEW` connection behaviour, run by `jpaPlatformPoolContractTest`; never part of `check`. The source set keeps the plan's name; the lane asserts behaviour rather than measuring, and no numeric performance bound is claimed anywhere from it. | | `performanceTest` | `src/jpaPlatformPerformanceTest` — 풀과 `REQUIRES_NEW` 연결 동작. `jpaPlatformPoolContractTest`가 돌리고, `check`에는 절대 들어가지 않는다. source set은 계획의 이름을 그대로 쓴다. 이 lane은 측정하지 않고 동작을 단언하며, 그로부터 어떤 성능 수치도 주장하지 않는다. |
Docker-dependent lanes fail closed rather than skipping, matching the existing Docker가 필요한 lane은 건너뛰지 않고 닫힌 채 실패한다. 이 leaf의 기존 관례 `PostgreSqlReadinessSupport.assertDockerAvailable()`과
`PostgreSqlReadinessSupport.assertDockerAvailable()` convention in this leaf. 같다.
## 4. Other deliberate substitutions ## 4. 그 밖에 일부러 바꾼 것
| Plan assumption | Repository reality | Adaptation | | 계획의 가정 | 저장소의 실제 | 대응 |
|---|---|---| |---|---|---|
| Gradle Kotlin DSL, `build-logic` convention plugin, `jpa-library-conventions.gradle.kts` | Groovy DSL, root `src/build.gradle` conventions (spotless google-java-format, checkstyle, SpotBugs + FindSecBugs, ErrorProne, `-Werror`, one-type-per-file), `LockMode.STRICT` dependency locking | Source sets and dependencies declared in `src/adapter/outbound/persistence-jpa/build.gradle`; `gradle.lockfile` regenerated with `resolveAndLockAll --write-locks`. | | Gradle Kotlin DSL, `build-logic` convention plugin, `jpa-library-conventions.gradle.kts` | Groovy DSL, `src/build-logic`의 convention plugin(Java로 씀: spotless google-java-format, checkstyle, SpotBugs + FindSecBugs, ErrorProne, `-Werror`, 파일 하나에 타입 하나), `LockMode.STRICT` 의존성 잠금 | source set과 의존성은 `src/adapter/outbound/persistence-jpa/build.gradle`에 선언했다. `gradle.lockfile`은 `resolveAndLockAll --write-locks`로 다시 만들었다. |
| Spring Boot 4.1 dependency management, Spring Data JPA 4.1 | Repository baseline is Spring Boot 4.0.8 | Versions are inherited from the repository BOM and never pinned per module, exactly as the plan requires ("do not override Hibernate/Flyway/Hikari versions outside the Boot BOM"). | | Spring Boot 4.1 의존성 관리, Spring Data JPA 4.1 | 저장소 기준선은 `src/gradle/libs.versions.toml`의 Spring Boot 버전이다 | 버전은 저장소 BOM에서 물려받고 모듈마다 고정하지 않는다. 계획이 요구하는 그대로다("do not override Hibernate/Flyway/Hikari versions outside the Boot BOM"). |
| Hibernate ORM 7.4 is the Stable provider | Boot 4.0.0 resolves `org.hibernate.orm:hibernate-core:7.1.8.Final` | The *declared* Stable provider baseline of the design stays 7.4 in `HibernateProviderPolicy`; the runtime provider version is read from Hibernate itself and reported. The collection-fetch-pagination gate runs against whatever provider the BOM resolves, and `HibernateProviderPolicy.driftsFromDeclaredBaseline()` makes the difference visible instead of hiding it behind a green check. | | Hibernate ORM 7.4가 Stable provider | 저장소 BOM이 `org.hibernate.orm:hibernate-core:7.1.8.Final`을 푼다(release registry의 `stable-tested-baseline`) | 설계의 *선언* Stable provider 기준선은 `HibernateProviderPolicy`에서 7.4로 남는다. 런타임 provider 버전은 Hibernate 자신에게서 읽어 보고한다. collection-fetch-pagination gate는 BOM이 푸는 provider에서 돌고, `HibernateProviderPolicy.driftsFromDeclaredBaseline()`이 차이를 초록 검사 뒤에 숨기지 않고 드러낸다. |
| PostgreSQL 16·17·18 Stable matrix | This leaf's existing evidence image is `postgres:16-alpine` | `PostgreSqlVersion` declares exactly PG 16, 17, 18. The default lane runs the repository's existing 16 image; 17 and 18 are selected by `-Pjpa.matrix.versions=16,17,18`, and an unknown or empty selection is an error rather than a skip. | | PostgreSQL 16·17·18 Stable matrix | 컨테이너 이미지는 `src/config/testing/container-images.properties`에 digest로 고정한다 | `PostgreSqlVersion`이 PG 16, 17, 18을 정확히 선언한다. 기본 lane은 16이고, 다른 major는 `-Pjpa.matrix.versions=<major>`로 고른다. 계약 suite(`JpaPlatformContractSupport.start()`)는 JVM 하나에 major 하나만 받는다. 여러 major를 한 번에 받는 것은 `StablePostgreSqlMatrixContractTest`뿐이다. 모르는 값이나 빈 선택은 건너뛰지 않고 오류다. |
| `settings.gradle.kts` module registration | Fail-closed 19-leaf registry | No registry change: leaf identity, Gradle path, allowed dependencies, and runtime memberships are unchanged. | | `settings.gradle.kts` 모듈 등록 | fail-closed registry | registry는 바꾸지 않았다. leaf 신원, Gradle path, 허용 의존은 그대로다. |
| `infra/jpa/{postgres,roles,toxiproxy}` | 이 repo는 운영 인프라 파일을 두지 않는다(2026-11-07 소유자 결정) | 2026-11-07에 지웠다(쓰는 곳이 없거나 운영 인프라 파일). 운영 DB 조건은 `docs/jpa/security.md`로 옮겼다. | | `infra/jpa/{postgres,roles,toxiproxy}` | 이 repo는 운영 인프라 파일을 두지 않는다(2026-11-07 소유자 결정) | 2026-11-07에 지웠다(쓰는 곳이 없거나 운영 인프라 파일). 운영 DB 조건은 `docs/jpa/security.md`로 옮겼다. |
| `docs/jpa/**`, `docs/adr/ADR-JPA-*`, `.github/workflows/jpa-*.yml` | Repository already owns `docs/` and `.github/workflows/` | Created at the same repository-relative paths. | | `docs/jpa/**`, `docs/adr/ADR-JPA-*`, `.github/workflows/jpa-*.yml` | 저장소가 이미 `docs/`와 `.github/workflows/`를 가진다 | 같은 저장소 상대 경로에 만들었다. |
| release blocking aggregate | `jpaReleaseQualification` (persistence-jpa `build.gradle`) over `persistence-jpa/release/release-registry.json`, run per PostgreSQL major by the `jpa-release-gate` job in `.github/workflows/release.yml` | The registry names the blocking lanes; Gradle defines how each lane runs; CI only schedules the matrix. | | | 릴리스를 막는 집계 | `persistence-jpa/release/release-registry.json` 위의 `jpaReleaseQualification`(persistence-jpa `build.gradle`). `.github/workflows/release.yml`의 `jpa-release-gate` job이 PostgreSQL major마다 돌린다 | registry가 막는 lane을 이름 대고, Gradle이 lane마다 도는 법을 정하고, CI는 matrix 일정만 잡는다. | |
| Per-task `git add` + `git commit` | `AGENTS.md`: commit policy is `human-only`; agents do not stage, commit, amend, or push | Implementation is delivered unstaged. This is the only plan step intentionally not executed, and it is recorded here. | | task마다 `git add` + `git commit` | `AGENTS.md`: 커밋 정책은 `human-only`다. 에이전트는 stage, commit, amend, push를 하지 않는다 | 구현은 stage하지 않은 채로 넘겼다. 일부러 하지 않은 계획 단계는 이것 하나이고, 여기에 기록한다. |
| Querydsl as an optional module dependency | Querydsl is not part of this repository's dependency set | `querydsl` is implemented against the plan's contracts with the Querydsl types kept behind `compileOnly`, so the Stable runtime classpath never carries Querydsl and a deployment opting in adds the artifact itself. | | Querydsl을 선택 모듈 의존성으로 | Querydsl은 이 저장소의 의존성 묶음에 없다 | `querydsl`은 계획의 계약대로 구현하되 Querydsl 타입을 `compileOnly` 뒤에 둔다. 그래서 Stable 런타임 classpath에는 Querydsl이 없고, 쓰기로 한 배포가 artifact를 직접 더한다. |
| Hibernate Envers as a module dependency | Envers is not part of this repository's dependency set | Same treatment as Querydsl: `compileOnly` + explicit opt-in, matching the plan's "Envers is opt-in and never enabled by a global base class". | | Hibernate Envers를 모듈 의존성으로 | Envers는 이 저장소의 의존성 묶음에 없다 | Querydsl과 같다. `compileOnly` + 명시적 opt-in. 계획의 "Envers is opt-in and never enabled by a global base class"와 맞는다. |
| `build-logic/src/test/kotlin/JpaModuleBoundaryTest.kt` | There is no `build-logic` project and no Kotlin source set; module boundaries are enforced by the registry itself | `verifyCleanArchitectureDependencies` plus `:app-bootstrap:architectureTest` assert the same property against `src/config/architecture/modules.json`, which is the authority the plan's test would have had to duplicate. | | `build-logic/src/test/kotlin/JpaModuleBoundaryTest.kt` | `src/build-logic`은 있지만 Kotlin source set은 없다 | 패키지 경계는 이 leaf의 `JpaModuleBoundaryTest`(§1)가, leaf 경계는 `verifyCleanArchitectureDependencies`와 `:app-bootstrap:architectureTest`가 `src/config/architecture/modules.json`을 정본으로 강제한다. |
| `PostgreSqlRuntimeRoleVerifierIntegrationTest` (Task 45) | The security lane is one suite in this leaf rather than a per-module `integrationTest` | `PostgreSqlSecurityContractTest` (tag `jpa-security`) exercises `PostgreSqlRuntimeRoleVerifier.verify` and `.requireSafe` against a real restricted role on a real server. | | `PostgreSqlRuntimeRoleVerifierIntegrationTest` (Task 45) | 보안 lane은 모듈마다의 `integrationTest`가 아니라 이 leaf의 suite 하나다 | `PostgreSqlSecurityContractTest`(tag `jpa-security`)가 실제 서버의 실제 제한 역할에 대고 `PostgreSqlRuntimeRoleVerifier.verify`와 `.requireSafe`를 돌린다. |
| `JpaSafetyProperties`, `JpaDataSourceProperties` | `NamingConventionTest` requires every `@ConfigurationProperties` type to end in `Settings` or `Policy` | Renamed to `JpaSafetySettings` and `JpaDataSourceSettings`. The bound property prefixes and every field are unchanged; only the class names move to this repository's convention. | | `JpaSafetyProperties`, `JpaDataSourceProperties` | `NamingConventionTest`는 모든 `@ConfigurationProperties` 타입 이름이 `Settings`나 `Policy`로 끝나기를 요구한다 | `JpaSafetySettings`로 이름을 바꿨다. 묶는 속성 prefix와 모든 칸은 그대로이고 클래스 이름만 이 저장소 관례로 옮겼다. `JpaDataSourceProperties`에 해당하는 설정 클래스는 지금 없다. datasource 검사는 `JpaDataSourceProfileValidator`가 한다. |
### Types relocated to keep the dependency direction legal ### 의존 방향을 지키려고 옮긴 타입
The plan's module map forbids `jpa-core-api` from depending on any other platform module. Three 계획의 모듈 지도는 `jpa-core-api`가 다른 플랫폼 모듈에 의존하는 것을 막는다. 설계가 하위 모듈에 둔 값 타입 셋을 core 계약이
value-only types the design places in a downstream module are consumed by a core contract, so they 쓰므로, 여기서는 core에 둔다. 셋 다 framework 의존이 없는 순수 값이라 옮기는 비용이 없다. 대안인, core 계약이 어댑터 패키지를
live in the core here instead. Each is a pure value with no framework dependency, so the relocation import하는 것은 모듈 지도가 지키려는 경계를 깬다.
costs nothing and the alternative — a core contract importing an adapter package — would break the
boundary the module map exists to hold.
| Type | Plan module | Repository package | Consumed by | | 타입 | 계획 모듈 | 저장소 패키지 | 쓰는 곳 |
|---|---|---|---| |---|---|---|---|
| `TransactionCompletionEvidence` | `jpa-transaction` | `…persistence.api.transaction` | `TransactionCompletionUnknownException` (design §17.3 types the field) | | `TransactionCompletionEvidence` | `jpa-transaction` | `…persistence.api.transaction` | `TransactionCompletionUnknownException`(설계서 §17.3이 칸의 타입을 정한다) |
| `ConstraintCode` | `jpa-postgresql` | `…persistence.api.error` | `ConstraintViolationDetails` (design §22.4) | | `ConstraintCode` | `jpa-postgresql` | `…persistence.api.error` | `ConstraintViolationDetails`(설계서 §22.4) |
| `SqlExceptionSqlStateResolver` | `jpa-transaction` | `…persistence.api.error` | the PostgreSQL translators | | `SqlExceptionSqlStateResolver` | `jpa-transaction` | `…persistence.api.error` | PostgreSQL translator들 |
The ArchUnit rule pack (`JpaArchitectureRules`, `EntityMappingCondition`, `EntityExposureCondition`) ArchUnit 규칙 묶음(`JpaArchitectureRules`, `EntityMappingCondition`, `EntityExposureCondition`)은 `…persistence.security` 운영
is placed in the `testkit` source set rather than in `…persistence.security` production code. ArchUnit 코드가 아니라 `testFixtures` source set에 둔다. ArchUnit은 테스트 라이브러리다. 규칙 묶음을 `main`에 두면 테스트에서만 도는
is a test library; putting the rule pack in `main` would drag it onto every deployment's runtime 코드를 위해 모든 배포의 런타임 classpath에 그것을 끌고 간다.
classpath to serve code that only ever runs in a test.
### 실제 서버에서 계약이 찾은 것
### Findings the contracts produced against a real server 설계의 규칙 둘이 조금 틀리게 적혀 있었고, 그것을 보여 준 것은 컨테이너 lane이다. 설계서 본문은 여전히 옛 내용이라 여기에
기록한다.
Two of the design's rules turned out to be stated slightly wrong, and the container lanes are what - **§17.2 커밋 모호함은 SQLSTATE class `08`만이 아니다.** 커밋이 진행 중인 backend에 `pg_terminate_backend`를 하면 연결
showed it. Both are recorded here because the design text still reads the old way. class 상태가 아니라 `57P01`(`admin_shutdown`)을 보고하고, 그것이 도착할 때 커밋 기록은 이미 WAL에 있을 수 있다. 이것을
담았던 classifier(`CommitFailureClassifier`)는 2026-09-25에 두 번째 트랜잭션 엔진과 함께 지웠다.
`PostgreSqlConcurrencyFailureContractTest`가 여전히 주입 지점을 고정한다.
- **schema-per-tenant 상태는 실행 결과로 짐작하지 말고 다시 읽어야 한다.** `MigrateResult`의 대상 버전은 이미 최신이던
tenant에서 비어 있어서, 그것을 기록하면 부분 rollout 중 마이그레이션한 tenant를 안 한 것으로 보고했다.
`SchemaTenantMigrationOrchestrator`가 이제 tenant의 schema history에서 적용된 버전을 읽는다.
- **§17.2 commit ambiguity is not only SQLSTATE class `08`.** `pg_terminate_backend` on a backend ## 5. 설계에서 바뀌지 않은 것
with a commit in flight reports `57P01` (`admin_shutdown`), not a connection-class state — and the
commit record may already be in the WAL when it arrives. The classifier that encoded this
(`CommitFailureClassifier`) was removed with the second transaction engine on 2026-09-25;
`PostgreSqlConcurrencyFailureContractTest` still pins the injection points.
- **Schema-per-tenant status must be read back, not inferred from the run.** `MigrateResult`'s
target version is empty for a tenant that was already current, so recording it reported migrated
tenants as unmigrated during a partial rollout. `SchemaTenantMigrationOrchestrator` now reads the
applied version from the tenant's schema history.
## 5. What is unchanged from the design - 도메인이 Entity, Embeddable, Repository, Query, 인덱스 요구, lock·soft-delete·감사 정책을 가진다. `GenericRepository<T, ID>`도,
Spring Data CRUD를 다시 구현한 것도 없다.
- Domain owns Entity, Embeddable, Repository, Query, index requirements, lock/soft-delete/audit - Application Service가 트랜잭션 경계를 가진다. OSIV는 모든 런타임 profile에서 false다.
policy. No `GenericRepository<T, ID>` and no Spring Data CRUD re-implementation exists. - `TransactionCompletionUnknownException`은 늘 `completionUnknown=true`, `retryable=false`를 보고하고, 자동으로 다시 시도하지
- Application Service owns the transaction boundary; OSIV is false in every runtime profile. 않는다. 맞추기가 처리한다.
- `TransactionCompletionUnknownException` always reports `completionUnknown=true`, - 재시도는 use case 전체를 새 트랜잭션과 새 Persistence Context에서 다시 돌린다.
`retryable=false`, and is never automatically retried — reconciliation handles it. - SQLSTATE 분류는 구조적이다(`40001`, `40003`, `40P01`, `23505`, `23503`, `23514`, `55P03`). 지역화된 메시지 문장을 파싱하지
- Retry re-executes the whole use case in a new transaction and a new Persistence Context. 않는다.
- SQLSTATE classification is structural (`40001`, `40003`, `40P01`, `23505`, `23503`, `23514`, - 운영 스키마 변경의 정본은 Flyway다. Hibernate는 검증만 하고, `ddl-auto`는 배포된 스키마를 바꾸지 않는다.
`55P03`) and never parses localized message text. - `CREATE INDEX CONCURRENTLY`에는 명시적인 비트랜잭션 마이그레이션 표시가 필요하다.
- Flyway is the source of truth for production schema change; Hibernate only validates; - 메트릭 label과 보통 로그에는 SQL 파라미터, entity ID, tenant ID, PII를 싣지 않는다.
`ddl-auto` never mutates a deployed schema. - Experimental 기능(multi-tenancy, RLS, schema·database tenancy, read replica)은 배포가 직접 만드는 라이브러리 코드이고 Stable
- `CREATE INDEX CONCURRENTLY` requires an explicit non-transactional migration marker. 조립에 들어가지 않는다. JPA 4, Hibernate 8, PostgreSQL 19는 기능이 아니라 `NOT_EXECUTABLE` probe다.
- Metric labels and ordinary logs never carry SQL parameters, entity IDs, tenant IDs, or PII. `backend.jpa.experimental.*` 스위치는 아무것도 읽지 않아서 2026-09-25에 지웠다.
- Experimental features (multi-tenancy, RLS, schema/database tenancy, read replica) are library code
a deployment constructs itself and never enter the Stable composition. JPA 4, Hibernate 8 and
PostgreSQL 19 are `NOT_EXECUTABLE` probes, not features. The `backend.jpa.experimental.*` flags
were removed on 2026-09-25: nothing read them.
+50 -63
View File
@@ -1,65 +1,56 @@
# JPA Platform Runbooks # JPA 플랫폼 runbook
Operator procedures for the failures this platform is designed to surface rather than hide. 이 플랫폼이 숨기지 않고 드러내도록 설계한 실패에 대한 운영자 절차다.
## A transaction reported completion unknown ## 트랜잭션이 완료를 모른다고 보고했다
**Signal:** a write use case failed with a commit-phase error (connection lost, `57P01`, class **신호:** 쓰기 use case가 `TransactionPort`에서 커밋 단계 오류(연결 끊김, `57P01`, class `08`)로 실패했다.
`08`) from `TransactionPort`.
**What it means:** the commit may or may not have happened. It is not a rollback. **뜻:** 커밋이 됐을 수도 안 됐을 수도 있다. 롤백이 아니다.
**Do not** re-run the use case. That is what the platform refused to do automatically, for the same use case를 다시 돌리지 **않는다**. 플랫폼이 같은 이유로 자동으로 하기를 거부한 일이다.
reason.
**Procedure:** **절차:**
1. Take the idempotency key or operation id of the failed request. 1. 실패한 요청의 멱등 키나 operation id를 꺼낸다.
2. Check the idempotency record for that key. 2. 그 키의 멱등성 기록을 확인한다.
3. Check the business row the use case would have written. 3. use case가 썼을 업무 행을 확인한다.
4. Check the outbox for a corresponding event. 4. outbox에 그에 맞는 이벤트가 있는지 확인한다.
5. If all three agree the write happened, stop — the request succeeded. 5. 셋이 모두 쓰기가 일어났다고 하면 멈춘다. 요청은 성공했다.
6. If all three agree it did not, the use case may be re-run. 6. 셋이 모두 일어나지 않았다고 하면 use case를 다시 돌려도 된다.
7. If they disagree or are inconclusive, escalate. An inconclusive answer is a legitimate outcome; 7. 서로 다르거나 결론이 나지 않으면 넘긴다. 결론 없음은 정당한 결과다. 짐작은 아니다.
guessing is not.
## Deadlock or serialization rate rising ## 교착이나 직렬화 실패 비율이 오른다
**Signal:** `DB_DEADLOCK` / serialization failures rising in the persistence error codes. **신호:** 영속성 오류 코드에서 `DB_DEADLOCK`·직렬화 실패가 오른다.
`SpringTransaction` does not retry, so each one reaches the caller. `SpringTransaction`은 다시 시도하지 않으므로 하나하나가 호출자에게 닿는다.
1. Group the failures by operation. A single operation dominating means a hot row or an 1. 실패를 operation별로 묶는다. operation 하나가 압도하면 hot row나 어긋난 잠금 순서다.
inconsistent lock order. 2. 교착이면 두 operation이 같은 행을 반대 순서로 잡는지 확인한다. 그것은 조정이 아니라 코드를 고칠 일이다.
2. For deadlocks, check whether two operations take the same rows in opposite orders — that is a 3. `SERIALIZABLE`에서의 직렬화 실패면 그 격리 수준이 정말 필요한지 확인한다.
code fix, not a tuning one.
3. For serialization failures under `SERIALIZABLE`, confirm the isolation is actually required.
## Pool exhaustion ## 풀 고갈
**Signal:** connection acquisition timeouts; `PoolMeasurement.pending` non-zero. **신호:** 연결 획득 시간 초과. `PoolMeasurement.pending`이 0이 아니다.
1. Check `REQUIRES_NEW` usage. It takes a second connection while pinning the first, so the pool 1. `REQUIRES_NEW` 사용을 확인한다. 첫 연결을 쥔 채 두 번째 연결을 잡으므로, 풀은 `(threads x (1 + depth)) + 1`을 채워야 한다.
must satisfy `(threads x (1 + depth)) + 1`. 2. 상한 있는 범위 밖의 streaming을 확인한다. 트랜잭션 밖으로 돌려준 `Stream`은 풀이 알아챌 때까지 연결을 쥔다.
2. Check for streaming outside a bounded scope — a `Stream` returned past the transaction holds its 3. DB 트랜잭션 안의 외부 호출을 확인한다. 설계가 그것을 금지하는 이유가 바로 그것이다. 그러면 HTTP 시간 초과가 그 시간
connection until the pool notices. 내내 연결을 쥔다.
3. Check for external calls inside a DB transaction. The design forbids them precisely because an
HTTP timeout then holds a connection for its whole duration.
## Flyway validation failed at startup ## 기동할 때 Flyway 검증이 실패했다
The deployment is running against a schema it was not built for. It failed closed, which is correct. 배포가 맞지 않는 스키마에서 돌고 있다. 닫힌 채 실패했고, 그것이 맞다.
1. Read the reported error codes (the messages are deliberately not propagated). 1. 보고된 오류 코드를 읽는다(메시지는 일부러 전달하지 않는다).
2. `CHECKSUM_MISMATCH` — an applied migration was edited afterwards. Find which change is missing 2. `CHECKSUM_MISMATCH` — 적용된 마이그레이션을 나중에 고쳤다. 이 DB에 어느 변경이 빠졌는지 찾는다. **`repair`를 돌리지
from this database. **Do not run `repair`**: it rewrites history to match the scripts, which 않는다.** repair는 이력을 스크립트에 맞춰 다시 써서, 증거를 지워 증상을 없앤다.
resolves the symptom by deleting the evidence. 3. `MISSING_SCRIPT` — 여기 적용된 마이그레이션이 이 빌드에 없다. 보통 옛 산출물로 되돌린 것이다.
3. `MISSING_SCRIPT` — a migration applied here is not in this build. Usually a rollback to an older
artifact.
## An invalid index exists ## 무효 인덱스가 있다 (An invalid index exists)
**Signal:** this query returns rows. **신호:** 이 쿼리가 행을 돌려준다.
```sql ```sql
select n.nspname || '.' || i.relname as invalid_index select n.nspname || '.' || i.relname as invalid_index
@@ -69,28 +60,24 @@ join pg_namespace n on n.oid = i.relnamespace
where not x.indisvalid; where not x.indisvalid;
``` ```
A concurrent build, rebuild or drop failed. The index is ignored by the planner and maintained by 동시 빌드, 재빌드, 삭제가 실패했다. planner는 그 인덱스를 무시하고, 모든 쓰기는 그것을 유지한다.
every write.
1. Confirm no build is currently running. An in-progress build looks identical in the catalog. 1. 지금 도는 빌드가 없는지 확인한다. 진행 중인 빌드도 카탈로그에서는 똑같이 보인다.
2. If a migration was building, rebuilding or dropping it, Flyway recorded that version as failed 2. 마이그레이션이 그것을 빌드, 재빌드, 삭제하던 중이었으면, Flyway는 그 버전을 실패(`success = false`)로 기록했고 그 행이
(`success = false`) and refuses every later deploy until that row is gone: dropping the index 사라질 때까지 뒤의 모든 배포를 거부한다. 인덱스를 지워도 풀리지 않는다. 다음 단계 대신
does not clear it. Follow [migration-failed.md](../runbooks/migration-failed.md) "Recover a [migration-failed.md](../runbooks/migration-failed.md) 「실패한 동시 인덱스 마이그레이션 복구 (Recover a failed
failed concurrent index migration" instead of the next step. It removes the cause, drops the concurrent index migration)」를 따른다. 그 절차는 원인을 없애고, 실패한 빌드나 재빌드가 남긴 인덱스를 지우고, 그 한 행을
index a failed build or rebuild left, and deletes that one row. It leaves the index a failed 지운다. 실패한 `DROP INDEX CONCURRENTLY`가 남긴 인덱스는 다시 배포가 지우도록 남긴다. 손으로 지우면 그 문장이 인덱스를
`DROP INDEX CONCURRENTLY` left, for the deploy again to drop: dropped by hand, that statement 찾지 못해 다시 실패한다.
finds no index and fails again. 3. 그렇지 않으면 마이그레이션 밖에서 `DROP INDEX CONCURRENTLY IF EXISTS <invalid_index>;`를 돌리고, 인덱스 마이그레이션을
3. Otherwise run `DROP INDEX CONCURRENTLY IF EXISTS <invalid_index>;` outside a migration, and 다시 적용한다.
re-apply the index migration.
The platform does not drop these automatically: on a rolling deploy every instance would race to 플랫폼은 이것을 자동으로 지우지 않는다. rolling deploy에서는 모든 인스턴스가, 다른 인스턴스가 곧 빌드를 끝낼 인덱스를
drop an index another instance was about to finish building. 지우려고 경주한다.
## The runtime role failed verification ## 런타임 역할이 검증에 실패했다
Startup refused because the runtime credential holds `CREATE`, or `search_path` contains an 런타임 자격 증명이 `CREATE`를 가지거나 `search_path`에 승인하지 않은 schema가 있어서 기동이 거부됐다.
unapproved schema.
This is not a false positive to be worked around. `docs/jpa/security.md` 「역할과 권한 — 운영 DB가 돌아갈 오탐이 아니다. `docs/jpa/security.md` 「역할과 권한 — 운영 DB가 갖춰야 할 것」대로 권한을 다시 맞춘다. 애플리케이션
갖춰야 할 것」대로 권한을 다시 맞춘다. 애플리케이션 자격 증명이 DDL을 가지면 다른 schema 보장을 하나도 자격 증명이 DDL을 가지면 다른 schema 보장을 하나도 지킬 수 없다.
지킬 수 없다.
+33 -36
View File
@@ -1,18 +1,18 @@
# Security # 보안
Design §36. Credential separation, privilege verification, and what never leaves the process. 설계서 §36. 자격 증명 분리, 권한 검증, 프로세스 밖으로 절대 나가지 않는 것.
## Three credentials ## 자격 증명 셋
| Role | May | | 역할 | 할 수 있는 것 |
|---|---| |---|---|
| `app_migration` | own the schema, apply migrations (DDL) | | `app_migration` | schema 소유, 마이그레이션 적용(DDL) |
| `app_runtime` | select, insert, update, delete (DML only) | | `app_runtime` | select, insert, update, delete(DML만) |
| `app_admin` | J4 operations — COPY, backfill, maintenance | | `app_admin` | J4 작업 — COPY, backfill, 정비 |
The separation is what makes "Flyway owns schema change" enforceable rather than aspirational. If 이 분리가 「schema 변경은 Flyway가 가진다」를 바람이 아니라 강제할 수 있는 규칙으로 만든다. 애플리케이션 자신의 자격 증명이
the application's own credential cannot execute DDL, then no code path, no library, and no injected DDL을 실행할 수 없으면, 애플리케이션이 무엇을 의도했든 어떤 코드 경로도, 라이브러리도, 주입된 문장도 실행 중에 schema를 바꿀
statement can alter the schema at runtime, regardless of what the application intended. 수 없다.
### 역할과 권한 — 운영 DB가 갖춰야 할 것 ### 역할과 권한 — 운영 DB가 갖춰야 할 것
@@ -50,9 +50,9 @@ statement can alter the schema at runtime, regardless of what the application in
확장(extension)은 필요 없다. JSONB, 배열, 범위, `SKIP LOCKED`, `ON CONFLICT`는 모두 PostgreSQL 본체 기능이다. 확장(extension)은 필요 없다. JSONB, 배열, 범위, `SKIP LOCKED`, `ON CONFLICT`는 모두 PostgreSQL 본체 기능이다.
## Startup verification ## 기동 검증
`PostgreSqlRuntimeRoleVerifier` asks the *server* what the connection can do: `PostgreSqlRuntimeRoleVerifier`가 연결이 무엇을 할 수 있는지 *서버*에 묻는다.
```sql ```sql
select current_user, select current_user,
@@ -61,38 +61,35 @@ select current_user,
has_database_privilege(current_user, current_database(), 'CREATE') has_database_privilege(current_user, current_database(), 'CREATE')
``` ```
Configuration cannot answer this. Effective privileges come from direct grants, inherited role 설정으로는 이것에 답할 수 없다. 실제 권한은 직접 grant, 물려받은 역할 membership, `PUBLIC` grant, schema 소유에서 오고, 배포
memberships, `PUBLIC` grants, and schema ownership, and no reading of a deployment manifest manifest를 읽어서는 그 조합을 믿을 만하게 되살릴 수 없다.
reconstructs that combination reliably.
Startup fails when the runtime role is not on the allowlist, or holds `CREATE` on the schema or the 런타임 역할이 허용 목록에 없거나, schema나 데이터베이스에 `CREATE`를 가지면 기동이 실패한다.
database.
## search_path ## search_path
`SearchPathPolicy` is an allowlist. `search_path` decides which schema an unqualified name resolves `SearchPathPolicy`는 허용 목록이다. `search_path`는 이름만 쓴 객체가 어느 schema로 풀리는지 정한다. 그래서 그 위에 쓸 수 있는
to, so a writable untrusted schema on it — classically `public`, where `CREATE` was granted broadly 믿지 못할 schema가 있으면(전형적으로 `public`. PostgreSQL 15 전에는 `CREATE`가 넓게 주어졌다) 심어 둔 테이블, 함수, 연산자가
before PostgreSQL 15 — lets a planted table, function, or operator shadow the real one, and the 진짜 것을 가리고, 애플리케이션은 알아채지 못한 채 그것을 실행한다. `$user`는 예외다. 연결한 역할만 그것을 소유한다.
application executes it without noticing. `$user` is exempt: only the connected role owns it.
Refusing the runtime role `CREATE` closes the same route from the other side. 런타임 역할에게 `CREATE`를 주지 않는 것이 같은 길을 반대쪽에서 막는다.
## What never leaves the process ## 프로세스 밖으로 절대 나가지 않는 것
- SQL parameter values, entity ids, tenant ids, and PII: not in exception messages, not in metric - SQL 파라미터 값, entity id, tenant id, PII. 예외 메시지에도, 메트릭 태그에도, 로그에도 없다. `JpaFailureContext`는 상한 있는
tags, not in logs. `JpaFailureContext` composes messages from bounded values only. 값으로만 메시지를 만든다.
- Constraint names reach the application as registered `ConstraintCode`s; an unregistered physical - 제약 이름은 등록된 `ConstraintCode`로 애플리케이션에 닿는다. 등록되지 않은 물리 이름은 그대로 넘기지 않고 상한 있는 unknown
name maps to a bounded unknown code rather than being passed through. 코드로 매핑한다.
- Cursors are HMAC-signed. An unsigned cursor is client-controlled ordering state. - cursor는 HMAC으로 서명한다. 서명 없는 cursor는 클라이언트가 다루는 정렬 상태다.
- The actuator report carries no JDBC URL, username, or SQL. - actuator 보고에는 JDBC URL, 사용자 이름, SQL이 없다.
## Injection surfaces, and how each is closed ## 주입 표면과 각각을 막는 법
| Surface | Why it cannot be a parameter | Closed by | | 표면 | 파라미터가 될 수 없는 이유 | 막는 것 |
|---|---|---| |---|---|---|
| sort field | part of ORDER BY | `SafeSortRegistry` allowlist | | 정렬 칸 | ORDER BY의 일부 | `SafeSortRegistry` 허용 목록 |
| JSON path | part of the statement | registered `JsonPathName` | | JSON 경로 | 문장의 일부 | 등록한 `JsonPathName` |
| schema name | an identifier | registered `SchemaTenantRegistry` | | schema 이름 | 식별자 | 등록한 `SchemaTenantRegistry` |
| COPY table | an identifier | registered `RegisteredCopyStatement` | | COPY 테이블 | 식별자 | 등록한 `RegisteredCopyStatement` |
Values are always bound. Identifiers are always registered. 값은 늘 묶는다. 식별자는 늘 등록한다.
+81 -95
View File
@@ -1,89 +1,79 @@
# JPA Persistence Platform — Support Matrix # JPA 영속성 플랫폼 — 지원 매트릭스
**This document is a rendering. The machine-readable source is **이 문서는 렌더링이다. 기계가 읽는 정본은
[`src/adapter/outbound/persistence-jpa/release/release-registry.json`](../../src/adapter/outbound/persistence-jpa/release/release-registry.json).** [`src/adapter/outbound/persistence-jpa/release/release-registry.json`](../../src/adapter/outbound/persistence-jpa/release/release-registry.json)이다.**
`JpaReleaseManifest` used to parse this file with regular expressions: every `PostgreSQL NN` it registry는 major마다 지원 수준을 칸으로 선언하고, gate마다 그 증거를 만드는 Gradle 태스크를 이름 댄다. 이 문서는
mentioned became a supported version, whatever table or sentence produced the match. An Experimental registry가 말하는 것을 설명한다. 표를 고치지 말고 registry를 고친다. 표가 따라오지 않으면 빌드가 실패한다.
major joined the Stable list, a version named once in prose counted as supported, and demoting a
major changed nothing so long as the string survived somewhere in the document. Now the registry
declares a support level per major as a field, each gate names the Gradle task that produces its
evidence, and this document describes what the registry says.
Being a rendering used to be a claim rather than a mechanism: the tables below were still typed by - `JpaReleaseRenderingTest`가 DB 표, gate 표, `release.yml`의 JPA matrix와 승격 목록을 registry와 비교한다.
hand, so a major demoted in the registry stayed Stable here and kept its full release job. - `jpaReleaseQualification` 집계 태스크는 막는 gate마다 그 태스크에 의존한다. 그래서 없는 태스크를 이름 댄 gate는 태스크
`JpaReleaseRenderingTest` now compares the database table, the gate table and `release.yml`'s JPA 그래프를 만들 때 실패한다.
matrix and promotion lists to the registry, and the `jpaReleaseQualification` aggregate depends on - `jpa-nightly.yml`의 matrix도 같은 비교를 받는다. Experimental major는 `.github/workflows`의 어떤 lane이 그것을 대상으로
every blocking gate's task, so a gate naming a task that does not exist fails when the task graph is 기록해야 하고, Stable lane은 그것을 돌리면 안 된다.
built. Edit the registry; these tables follow, or the build fails.
Two renderings stayed outside that comparison until they were added to it. `jpa-nightly.yml` runs > 이력: 전에는 `JpaReleaseManifest`가 이 파일을 정규식으로 읽었다. 어느 표나 문장에서 나왔든 `PostgreSQL NN`이 지원
its own matrix and nothing checked it, so a demotion corrected the release lane and left the nightly > 버전이 됐다. Experimental major가 Stable 목록에 들어갔고, 본문에 한 번 나온 버전이 지원으로 셌고, 문자열이 문서
lane certifying the major. And an Experimental major's "compatibility lane only" named no file: the > 어딘가에 남아 있는 한 major를 내려도 아무것도 바뀌지 않았다. registry로 옮긴 뒤에도 한동안 아래 표는 손으로 썼다.
lane existed, but the registry, this document and the release workflow could each be read end to end > 그래서 registry에서 내린 major가 여기서는 Stable로 남고 자기 전체 릴리스 job을 계속 가졌다. `jpa-nightly.yml`은 자기
without establishing that, so a reader looking for it concluded there was none. An Experimental major > matrix를 아무도 확인하지 않아서, 내리기가 릴리스 lane만 고치고 nightly lane은 그 major를 계속 인증했다. Experimental
now has to be recorded as the target of a lane in `.github/workflows`, and a Stable lane may not run > major의 「compatibility lane only」는 어떤 파일도 가리키지 않았다. lane은 있었지만 registry, 이 문서, 릴리스 workflow를
it. > 끝까지 읽어도 그것을 알 수 없어서, 찾던 사람은 없다고 결론 냈다.
## Database ## 데이터베이스
| Database | Support | Evidence | | Database | Support | Evidence |
|---|---|---| |---|---|---|
| PostgreSQL 16 | Stable | full contract suite, release lane (own matrix job) | | PostgreSQL 16 | Stable | 전체 계약 suite, 릴리스 lane(자기 matrix job) |
| PostgreSQL 17 | Stable | full contract suite, release lane (own matrix job) | | PostgreSQL 17 | Stable | 전체 계약 suite, 릴리스 lane(자기 matrix job) |
| PostgreSQL 18 | Stable | full contract suite, release lane (own matrix job) | | PostgreSQL 18 | Stable | 전체 계약 suite, 릴리스 lane(자기 matrix job) |
| PostgreSQL 19 | Experimental | [`jpa-next.yml`](../../.github/workflows/jpa-next.yml) — `NOT_EXECUTABLE`: no `postgres:19-alpine` is published, so no container of that major has been started; promotion requires an ADR | | PostgreSQL 19 | Experimental | [`jpa-next.yml`](../../.github/workflows/jpa-next.yml) — `NOT_EXECUTABLE`: `postgres:19-alpine`이 게시되지 않아 그 major의 컨테이너를 띄운 적이 없다. 승격에는 ADR이 필요하다 |
| H2 | Local convenience | **never** evidence of PostgreSQL behaviour | | H2 | Local convenience | PostgreSQL 동작의 증거가 **절대** 아니다 |
Each major gets its **own release job**, because for a while it did not. The release lane passed major마다 **자기 릴리스 job**이 있다. `release.yml`의 `jpa-release-gate` job이 major마다 job 하나로 펼치고, 승격 job은 세
`-Pjpa.matrix.versions=16,17,18` to a `JpaPlatformContractSupport.start()` that used major의 증거가 모두 같은 커밋 SHA를 지니기를 요구한다. 그래서 major 하나가 빠지면 그 증거가 아니라 릴리스가 빠진다.
`selectedVersions().get(0)`, so the whole integration suite ran against PostgreSQL 16 and this table `JpaPlatformContractSupport.start()`는 여러 버전 선택을 아예 거부한다.
recorded 17 and 18 as fully covered on the strength of a three-assertion smoke test. `start()` now
refuses a multi-version selection outright, the `jpa-release-gate` job in `release.yml` fans out to one job per major, and a
promotion job requires all three majors' evidence to carry the same commit SHA — so a removed major
removes the release, not the evidence for it.
**Provider baseline.** The gates run against the Hibernate version the Spring Boot BOM resolves — > 이력: 한동안 그렇지 않았다. 릴리스 lane이 `-Pjpa.matrix.versions=16,17,18`을 `selectedVersions().get(0)`을 쓰는
**7.1.8.Final** — which the registry records as `stable-tested-baseline`. This document previously > `JpaPlatformContractSupport.start()`에 넘겼으므로, 통합 suite 전체가 PostgreSQL 16에만 돌았다. 이 표는 단언 셋짜리
called 7.4 the Stable baseline and the pagination gate was named `hibernate-7.4-fetch-pagination`, > smoke test를 근거로 17과 18을 전부 덮었다고 적었다.
so every run of that gate produced evidence labelled with a provider it had never executed against.
7.4 is recorded as `compatibility-target`; it becomes the baseline when a full lane has actually run
on it.
H2 is not a second production target. It reports different SQLSTATEs for the same violation, no JSONB **provider 기준선.** gate는 Spring Boot BOM이 푸는 Hibernate 버전 **7.1.8.Final**에서 돈다. registry는 그것을
operators, no range types, and no concurrent index builds. A green H2 run is evidence that the code `stable-tested-baseline`으로 기록한다. 7.4는 `compatibility-target`으로 기록하고, 전체 lane이 실제로 그 버전에서 돈 뒤에
compiles and runs, and nothing more. 기준선이 된다.
`SKIP LOCKED` needs its own sentence, because two documents said different things about it. The > 이력: 이 문서는 전에 7.4를 Stable 기준선이라 불렀고 페이지네이션 gate 이름도 `hibernate-7.4-fetch-pagination`이었다.
module's `CLAUDE.md` records a measurement: H2 2.4.240 accepts `FOR UPDATE SKIP LOCKED` and does > 그래서 그 gate를 돌릴 때마다 한 번도 돌려 보지 않은 provider 이름이 붙은 증거가 나왔다.
genuinely skip locked rows, which is why the outbox claim SQL is identical on both vendors. This
document previously said H2 has no such guarantee. Both are right about different questions, and
the distinction is the point: **observed behaviour in the version we measured is not a production
guarantee, and it is never PostgreSQL contract evidence.** The measurement is why the claim SQL
needs no vendor branch; the absence of a guarantee is why every concurrency contract still runs
against a real PostgreSQL.
## Specification and provider H2는 두 번째 운영 대상이 아니다. 같은 위반에 다른 SQLSTATE를 보고하고, JSONB 연산자도, range 타입도, 동시 인덱스
빌드도 없다. H2에서 통과한 실행은 코드가 컴파일되고 돈다는 증거일 뿐이다.
| Component | Stable | Experimental | `SKIP LOCKED`는 따로 한 문장이 필요하다. 두 문서가 다른 말을 했기 때문이다. 모듈의 `CLAUDE.md`는 측정을 기록한다.
H2 2.4.240은 `FOR UPDATE SKIP LOCKED`를 받고 잠긴 행을 정말로 건너뛴다. 그래서 outbox claim SQL이 두 vendor에서 같다. 이
문서는 전에 H2에 그런 보장이 없다고 했다. 둘은 서로 다른 질문에 각각 맞았고, 그 구별이 요점이다. **측정한 버전에서 관찰한
동작은 운영 보장이 아니고, PostgreSQL 계약 증거는 더욱 아니다.** 측정 덕분에 claim SQL에 vendor 분기가 필요 없고, 보장이
없으므로 모든 동시성 계약은 여전히 실제 PostgreSQL에서 돈다.
## 명세와 provider
| 구성 요소 | Stable | Experimental |
|---|---|---| |---|---|---|
| Jakarta Persistence | 3.2 | 4.0 (lane) | | Jakarta Persistence | 3.2 | 4.0 (lane) |
| Hibernate ORM | 7.4 declared baseline | 8 (lane) | | Hibernate ORM | 7.4 선언 기준선 | 8 (lane) |
| Spring Boot | repository BOM | — | | Spring Boot | 저장소 BOM | — |
The Hibernate row needs a note. The design declares 7.4 as the Stable provider; this repository's Hibernate 줄에는 설명이 필요하다. 설계서는 7.4를 Stable provider로 선언하고, 이 저장소의 Spring Boot BOM은 7.1.x를 푼다.
Spring Boot BOM resolves 7.1.x. `HibernateProviderPolicy` holds both — the declared baseline as a `HibernateProviderPolicy`가 둘을 다 가진다. 선언 기준선은 상수로, 풀린 버전은 Hibernate 자신에게서 읽는다.
constant, the resolved version read from Hibernate itself — and `driftsFromDeclaredBaseline()` makes `driftsFromDeclaredBaseline()`이 상수를 상수와 비교하는 대신 그 차이를 드러낸다.
the difference visible instead of asserting a constant against itself. See [repository-adaptation.md](repository-adaptation.md) §4를 본다.
[repository-adaptation.md](repository-adaptation.md) §4.
## Capability support levels ## capability 지원 수준
The levels are the ones `JpaPlatformAutoConfiguration.capabilities()` reports through the 수준은 `jpaplatform` actuator 엔드포인트가 `JpaPlatformReport.platformCapabilities()`로 보고하는 값이다. 마지막 세
`jpaplatform` actuator endpoint. Advanced and Experimental rows are library code a service calls 줄(기술 감사, multi-tenancy, read replica)은 그 보고에 없고 이 문서가 정한다. Advanced와 Experimental 줄은 서비스가 직접
itself (`src/adapter/outbound/persistence-jpa/README.md` "라이브러리 API"). 부르는 라이브러리 코드다(`src/adapter/outbound/persistence-jpa/README.md` 「라이브러리 API」).
| Capability | Level | | capability | 수준 |
|---|---| |---|---|
| Keyset pagination | Stable | | Keyset pagination | Stable |
| Flyway schema gate | Stable | | Flyway schema gate | Stable |
@@ -95,44 +85,40 @@ itself (`src/adapter/outbound/persistence-jpa/README.md` "라이브러리 API").
| PostgreSQL array and range | Advanced | | PostgreSQL array and range | Advanced |
| Bulk DML | Advanced | | Bulk DML | Advanced |
| Hibernate `StatelessSession` | Advanced | | Hibernate `StatelessSession` | Advanced |
| PostgreSQL `COPY` | Admin (J4) | | PostgreSQL `COPY` | Advanced (admin 자격 증명 필요) |
| Hibernate second-level cache | Advanced | | Hibernate second-level cache | Advanced |
| Hibernate Envers | Advanced | | Hibernate Envers | Advanced |
| Technical auditing — `audit/AuditableEntity` | Stable (canonical) | | 기술 감사 — `audit/AuditableEntity` | Stable (canonical) |
| Multi-tenancy (column, RLS, schema, database) | Experimental | | Multi-tenancy (column, RLS, schema, database) | Experimental |
| Consistency-aware read replica | Experimental | | 일관성을 아는 read replica | Experimental |
## Release gates ## 릴리스 gate
Each row is a way the platform could pass its tests and still be wrong in production. 줄마다, 플랫폼이 테스트를 통과하고도 운영에서 틀릴 수 있는 길 하나다.
| Gate | Kind | What it prevents | | Gate | Kind | 막는 것 |
|---|---|---| |---|---|---|
| `postgresql-contract` | gate | a release whose only database evidence came from H2 | | `postgresql-contract` | gate | DB 증거가 H2에서만 나온 릴리스 |
| `completion-unknown-no-retry` | gate | automatically re-running a write that may already have committed | | `completion-unknown-no-retry` | gate | 이미 커밋됐을 수 있는 쓰기를 자동으로 다시 돌림 |
| `osiv-disabled` | gate | lazy loading from the view layer, one query per rendered row | | `osiv-disabled` | gate | view 계층에서의 lazy loading, 렌더링한 행마다 쿼리 하나 |
| `flyway-validate` | gate | Hibernate mutating a deployed schema, or running against one it was not built for | | `flyway-validate` | gate | Hibernate가 배포된 스키마를 바꾸거나, 맞지 않는 스키마에서 돎 |
| `runtime-role-no-ddl` | gate | the application's own credential being able to alter or drop schema objects | | `runtime-role-no-ddl` | gate | 애플리케이션 자신의 자격 증명으로 스키마 객체를 바꾸거나 지울 수 있음 |
| `collection-fetch-pagination` | gate | a paged collection fetch silently reading the whole table and paginating in memory | | `collection-fetch-pagination` | gate | 페이지 단위 collection fetch가 몰래 테이블 전체를 읽고 메모리에서 페이지를 나눔 |
### The audit mechanism ### 감사 방식
`audit/AuditableEntity` is the only one: `created_*`/`updated_*`, a 256-character actor, stamped 감사 방식은 `audit/AuditableEntity` 하나다. `created_*`/`updated_*`, 256자 actor이고, repository 어댑터가 명시적으로
explicitly by the repository adapter. 서비스의 엔티티는 이것을 상속하고, 마이그레이션도 이 열에 찍는다. 서비스의 엔티티는 이것을 상속하고, 마이그레이션도 이 열에 맞춰 썼다. 두 번째 방식인 Spring Data listener 기반
맞춰 썼다. A second, Spring Data listener-based mechanism (`auditing/AuditMetadata`) was never (`auditing/AuditMetadata`)은 한 번도 조립되지 않아서 지웠다. `JpaAuditMechanismRule.entitiesUseExactlyOneAuditMechanism`이
composed and has been removed; `JpaAuditMechanismRule.entitiesUseExactlyOneAuditMechanism` keeps it 그것이 엔티티에 돌아오지 못하게 막는다.
from coming back on an entity.
The mechanism does not reach a bulk or native update. It stamps on an ordinary save in the adapter, 이 방식은 bulk·native update에 닿지 않는다. 어댑터의 보통 save에서 찍으므로, DB로 바로 가는 문장은 감사 열을 앞 save의
so a statement that goes straight to the database leaves the audit columns showing the previous save. 값으로 남긴다. 그래서 감사 대상 엔티티의 bulk update는 문장 안에서 감사 열을 설정해야 하고,
A bulk update of an audited entity must therefore set the audit column in the statement, which `JpaAuditMechanismRule.bulkUpdatesOfAuditedEntitiesStampAudit`가 운영 그래프에서 그것을 확인한다.
`JpaAuditMechanismRule.bulkUpdatesOfAuditedEntitiesStampAudit` checks over the production graph.
## Explicitly unsupported ## 지원하지 않는다고 밝힌 것
- Reactive JPA. JPA is a blocking specification; a reactive facade over it moves the blocking call - Reactive JPA. JPA는 blocking 명세다. 그 위의 reactive facade는 blocking 호출을 없애는 게 아니라 event loop로 옮긴다.
onto an event loop rather than removing it. - 운영 스키마를 쓰는 Hibernate. `ddl-auto`는 배포된 스키마를 절대 바꾸지 않는다.
- Hibernate as the production schema writer. `ddl-auto` never mutates a deployed schema. - 플랫폼이 가진 generic CRUD repository. 도메인이 자기 repository를 가진다(설계서 §10.1).
- A platform-owned generic CRUD repository. Domains own their repositories (design §10.1). - 완료를 모르는 트랜잭션의 자동 맞추기. 플랫폼은 기록하고, 도메인이 푼다.
- Automatic reconciliation of a completion-unknown transaction. The platform records; the domain
resolves.
+34 -43
View File
@@ -1,65 +1,56 @@
# Transaction Guide # 트랜잭션 가이드
Design §15-§20. What owns a transaction, what may be retried, and what must never be. 설계서 §15-§20. 무엇이 트랜잭션을 가지고, 무엇을 다시 시도해도 되고, 무엇은 절대 안 되나.
## The application service owns the boundary ## 경계는 애플리케이션 서비스가 가진다
Repository adapters do not open transactions. The use case does, through `TransactionPort`, repository 어댑터는 트랜잭션을 열지 않는다. use case가 `TransactionPort`로 연다. 작업 단위는 업무 결정이고, 그것이 어디서
because the unit of work is a business decision and only the use case knows where it starts and 시작하고 끝나는지는 use case만 알기 때문이다. 구현은 `SpringTransaction` 하나다. Spring의 `PlatformTransactionManager` 위에
ends. `SpringTransaction` is the only implementation: one pre-built `TransactionTemplate` per mode마다 미리 만든 `TransactionTemplate` 하나를 두고, 모든 mode가 `READ_COMMITTED`로 돌며 시간 상한이 있다.
mode over Spring's `PlatformTransactionManager`, every mode running at `READ_COMMITTED` and
bounded in time.
- **Isolation** is pinned on the pool, not per transaction: the module defaults set - **격리 수준**은 트랜잭션마다가 아니라 풀에 고정한다. module defaults가
`spring.datasource.hikari.transaction-isolation: TRANSACTION_READ_COMMITTED` and `spring.datasource.hikari.transaction-isolation: TRANSACTION_READ_COMMITTED`를 두고, `HikariPoolConstraintValidator`가 다른
`HikariPoolConstraintValidator` refuses any other level. A template that names the level makes 수준을 거부한다. 수준을 이름 대는 template은 begin마다 pgjdbc가 서버에 그것을 묻게 한다(`SHOW TRANSACTION ISOLATION LEVEL`).
pgjdbc ask the server for it (`SHOW TRANSACTION ISOLATION LEVEL`) at every begin. - **시간 상한**: `app.persistence-jpa.transaction.write-timeout`(`inWrite`, `inRootWrite`)과 `read-timeout`(`inRead`), 기본값은
- **Time bound**: `app.persistence-jpa.transaction.write-timeout` (`inWrite`, `inRootWrite`) and 각각 30 s다. `inNew`는 30 s로 고정이다. Spring이 남은 시간을 문장마다 넘기므로 서버가 느린 문장이나 잠금 대기를 취소하고
`read-timeout` (`inRead`), 30 s each by default; `inNew` is fixed at 30 s. Spring hands the (`DB_QUERY_CANCELED`) 연결은 풀로 돌아간다. 더 오래 걸려야 하는 작업 단위는 보통 상한을 올릴 이유가 아니라 나눠야 할 batch
remaining time to each statement, so the server cancels a slow statement or lock wait 작업이다.
(`DB_QUERY_CANCELED`) and the connection returns to the pool. A unit of work that needs longer
is usually a batch job that should be split, not a reason to raise the bound.
| Call | Propagation | When | | 호출 | 전파 | 언제 |
|---|---|---| |---|---|---|
| `inWrite` | `REQUIRED`, read-write | command default | | `inWrite` | `REQUIRED`, 읽기-쓰기 | command 기본 |
| `inRootWrite` | `REQUIRED`, read-write, rejects an ambient transaction before running | orchestration that must prove a physical commit | | `inRootWrite` | `REQUIRED`, 읽기-쓰기, 돌기 전에 바깥 트랜잭션을 거부 | 물리 커밋을 증명해야 하는 조율 |
| `inRead` | `REQUIRED`, read-only | query default | | `inRead` | `REQUIRED`, 읽기 전용 | query 기본 |
| `inNew` | `REQUIRES_NEW`, read-write | outbox / audit / compensation that must commit on its own | | `inNew` | `REQUIRES_NEW`, 읽기-쓰기 | 혼자 커밋해야 하는 outbox / 감사 / 보상 |
Open Session In View is off in every runtime profile. It is on by default in Spring Boot, which is Open Session In View는 모든 런타임 profile에서 꺼져 있다. Spring Boot에서는 기본으로 켜져 있어서, 설정 리뷰를 믿지 않고
why `JpaDangerousConfigurationGuard` fails startup rather than trusting configuration review. `JpaDangerousConfigurationGuard`가 기동을 실패시킨다.
`REQUIRES_NEW` acquires a second physical connection while pinning the first, so the pool must `REQUIRES_NEW`는 첫 물리 연결을 쥔 채 두 번째를 잡으므로 풀은 다음을 채워야 한다.
satisfy:
```text ```text
maximumPoolSize >= (concurrent_threads x (1 + max_requires_new_depth)) + 1 maximumPoolSize >= (concurrent_threads x (1 + max_requires_new_depth)) + 1
``` ```
## Nothing is retried by the port ## port는 아무것도 다시 시도하지 않는다
`SpringTransaction` runs the action once. A failure rolls back and propagates, translated to `SpringTransaction`은 action을 한 번 돌린다. 실패하면 롤백하고 넘기며, SQLSTATE를 알면 공유 영속성 오류 코드로 바꾼다.
the shared persistence error codes where the SQLSTATE is known; a lost `@Version` race has no 잃은 `@Version` 경주는 SQLSTATE가 없고 `DB_OPTIMISTIC_CONFLICT`(409)로 보고한다. 다시 시도하기로 한 호출자는 문장 하나를 다시
SQLSTATE and is reported as `DB_OPTIMISTIC_CONFLICT` (409). A caller that decides to retry must 보내지 말고 use case 전체를 새 트랜잭션에서 다시 돌린다. 낙관적 충돌이나 직렬화 실패는 시도가 기준으로 계산한 상태가 더는
re-run the whole use case in a new transaction — never re-issue one statement — because an 커밋된 상태가 아니라는 뜻이기 때문이다.
optimistic conflict or a serialization failure means the state the attempt computed against is no
longer the committed state.
A second engine with named policies, deadline budgets, transaction-local timeouts and automatic > 이력: 이름 있는 정책, 마감 예산, 트랜잭션 로컬 시간 상한, 자동 전체 트랜잭션 재시도를 가진 두 번째 엔진
full-transaction retry (`SpringJpaTransactionExecutor`, `FullTransactionRetryCoordinator`, > (`SpringJpaTransactionExecutor`, `FullTransactionRetryCoordinator`, `PolicyTransactionPort`)이 이것 옆에 있다가
`PolicyTransactionPort`) existed next to this one and was removed on 2026-09-25. Its last commit is > 2026-09-25에 지워졌다. 마지막 커밋은 `docs/capability-status.md`에 있다.
recorded in `docs/capability-status.md`.
## Completion unknown ## 완료를 모름
A connection can break while a commit is in flight; the server may have committed and only the 커밋이 진행 중일 때 연결이 끊길 수 있다. 서버는 커밋했고 확인 응답만 잃었을 수 있다. `TransactionCompletionUnknownException`은
acknowledgement was lost. `TransactionCompletionUnknownException` is never retried, and the type 절대 다시 시도하지 않고, 타입 체계가 그것을 강제한다. `JpaFailureContext`는 다시 시도할 수 있는 완료 모름 실패를 표현하기를
system enforces it: `JpaFailureContext` refuses to represent a retryable completion-unknown failure. 거부한다. port 자신은 아무것도 다시 시도하지 않으므로, 그런 커밋은 호출자에게 실패로 정확히 한 번 나타난다
The port itself retries nothing, so such a commit surfaces to the caller as a failure exactly once
(`PostgreSqlTransactionIntegrationTest#connectionLossDuringCommitSurfacesAsCompletionUnknownAndIsNeverRetried`). (`PostgreSqlTransactionIntegrationTest#connectionLossDuringCommitSurfacesAsCompletionUnknownAndIsNeverRetried`).
Recovery is reconciliation, not retry: 복구는 재시도가 아니라 맞추기다.
```text ```text
check the idempotency record -> check the business row -> check the outbox check the idempotency record -> check the business row -> check the outbox
+1 -1
View File
@@ -64,7 +64,7 @@ verify-feature-scaffold.sh
-> new-feature.sh Operation / Notification / Common (템플릿 패키지 이름: 거절되고 아무것도 안 씀) -> new-feature.sh Operation / Notification / Common (템플릿 패키지 이름: 거절되고 아무것도 안 씀)
-> new-feature.sh Invoice, new-feature.sh PurchaseOrder (한 단어 / 여러 단어) -> new-feature.sh Invoice, new-feature.sh PurchaseOrder (한 단어 / 여러 단어)
-> 생성 파일이 있는지 확인 -> 생성 파일이 있는지 확인
-> ./gradlew 5 leaf check + architectureCheck -> 생성물이 닿는 leaf(domain-core, application-core, identifier, web, app-bootstrap) check + architectureCheck
-> 각 leaf 테스트 결과에 생성된 테스트 클래스가 실행·통과로 남았는지 확인 -> 각 leaf 테스트 결과에 생성된 테스트 클래스가 실행·통과로 남았는지 확인
-> 임시 디렉터리 삭제 -> 임시 디렉터리 삭제
``` ```
+64 -66
View File
@@ -1,99 +1,97 @@
# Advanced — CSFLE and Queryable Encryption # Advanced — CSFLE와 Queryable Encryption
**Capabilities:** `MongoCapability.CSFLE`, `MongoCapability.QUERYABLE_ENCRYPTION` **Capability:** `MongoCapability.CSFLE`, `MongoCapability.QUERYABLE_ENCRYPTION`
**Enablement:** library API, no configuration property. The service's own adapter constructs the **켜는 법:** 라이브러리 API다. 설정 속성은 없다. 서비스의 어댑터가 진입점을 만들 때
entry point with a `MongoAdvancedCapabilityGuard` built from `MongoAdvancedCapabilityFlags` that `MongoAdvancedCapabilityGuard`를 넘긴다. 이 guard는 그 capability를 켠 `MongoAdvancedCapabilityFlags`로
enables the capability; construction is refused otherwise. 만든다. 켜지 않았으면 생성 자체가 거부된다.
**Status:** Advanced. **상태:** Advanced.
## Requirements ## 요구 사항
| | | | | |
|---|---| |---|---|
| Topology | Replica set or sharded cluster. | | 토폴로지 | replica set 또는 sharded cluster. |
| Server | MongoDB 7.0 or 8.0 (see §4 for the 8.0 query-type limits). | | 서버 | MongoDB 7.0 또는 8.0(8.0의 query type 제한은 4절). |
| Privilege | `MongoPrincipalRole.ENCRYPTION_ADMIN` for the key vault; the application role never holds it. | | 권한 | key vault에는 `MongoPrincipalRole.ENCRYPTION_ADMIN`이 필요하다. 애플리케이션 role은 이 권한을 갖지 않는다. |
| Environment | A real KMS and key vault. A local key provider does not exercise any of the failure modes that matter. | | 환경 | 실제 KMS와 key vault. 로컬 key provider는 중요한 실패 모드를 하나도 재현하지 못한다. |
## 1. CSFLE ## 1. CSFLE
`MongoCsfleProfile` binds a collection (`database` + `collection`) to its `MongoCsfleFieldPolicy` `MongoCsfleProfile`은 collection 하나(`database` + `collection`)를 세 가지에 묶는다:
list, a key vault `MongoCredentialReference` and the key vault namespace. `MongoCsfleClientFactory` `MongoCsfleFieldPolicy` 목록, key vault용 `MongoCredentialReference`, key vault namespace.
builds the encrypted client settings from it: the `$jsonSchema` is generated from the field policies `MongoCsfleClientFactory`가 이 profile로 암호화 client 설정을 만든다.
(a dotted path becomes nested `properties`) and keyed by the namespace `database.collection`, and the
key vault client is built from the profile's own credential through `MongoCredentialResolver`.
An automatic-encryption schema names a data key by id, not by alias. The adopter resolves each - `$jsonSchema`는 field policy에서 생성한다. 점으로 이은 경로는 중첩된 `properties`가 된다.
`MongoCsfleFieldPolicy.keyAlias()` against the key vault (for example - schema의 키는 namespace `database.collection`이다.
`ClientEncryption.getKeyByAltName`) and passes the alias → key id map to `settingsFor`; an alias with - key vault client는 profile 자신의 credential로 `MongoCredentialResolver`를 거쳐 만든다.
no id is refused. Deterministic fields are typed `string` in the schema.
자동 암호화 schema는 data key를 별칭이 아니라 id로 가리킨다. 그래서 도입하는 쪽이 각
`MongoCsfleFieldPolicy.keyAlias()`를 key vault에서 찾아(예: `ClientEncryption.getKeyByAltName`)
별칭 → key id 맵을 `settingsFor`에 넘긴다. id가 없는 별칭은 거부한다. deterministic 필드는 schema에서
`string` 타입이다.
`MongoCsfleMode`: `MongoCsfleMode`:
| Mode | Queryable | Trade-off | | 모드 | 조회 가능 | 득실 |
|---|---|---| |---|---|---|
| `RANDOMIZED` | no | Same plaintext encrypts differently each time. The safe default. | | `RANDOMIZED` | 아니다 | 같은 평문도 매번 다르게 암호화된다. 안전한 기본값이다. |
| `DETERMINISTIC` | equality only | Same plaintext always yields the same ciphertext, so equality works — and so does frequency analysis. | | `DETERMINISTIC` | 같음 비교만 | 같은 평문은 늘 같은 암호문이 된다. 그래서 같음 비교가 된다. 빈도 분석도 같이 된다. |
| `UNINDEXED` | no | Stored encrypted, excluded from any index. | | `UNINDEXED` | 아니다 | 암호화해 저장하고 어떤 index에도 넣지 않는다. |
`MongoCsfleFieldPolicy.forPii(field, queryable)` defaults to `RANDOMIZED` when the field is not `MongoCsfleFieldPolicy.forPii(field, queryable)`는 조회하지 않는 필드면 `RANDOMIZED`를 고른다.
queried. Deterministic encryption requires a written `equalityQueryJustification`; the constructor deterministic 암호화에는 글로 쓴 `equalityQueryJustification`이 필요하다. 생성자는 빈 값을 거부하고
refuses a blank one, naming frequency analysis. A low-cardinality deterministic field (a status, a 빈도 분석을 이유로 든다. 값의 가짓수가 적은 deterministic 필드(상태, 국가, boolean)는 collection을 읽을
country, a boolean) leaks its distribution to anyone who can read the collection, which is the party 수 있는 누구에게나 분포를 드러낸다. 그 누구가 바로 암호화가 막으려던 상대다.
encryption was protecting against.
## 2. Queryable Encryption ## 2. Queryable Encryption
`MongoQueryableEncryptionProfile` binds a collection to `MongoEncryptedFieldDescriptor` entries. `MongoQueryableEncryptionProfile`은 collection 하나를 `MongoEncryptedFieldDescriptor` 항목들에 묶는다.
`MongoQueryableEncryptionQueryType` has exactly two values: `MongoQueryableEncryptionQueryType`의 값은 둘뿐이다.
- `EQUALITY` - `EQUALITY`
- `RANGE` — must declare its domain (`min`, `max`). The constructor refuses a range field without one, - `RANGE` — 값의 범위(`min`, `max`)를 선언해야 한다. 생성자는 범위가 없는 range 필드를 거부한다.
because changing the domain later means re-encrypting the field. 범위를 나중에 바꾸면 그 필드를 다시 암호화해야 하기 때문이다.
`MongoQueryableEncryptionCollectionManager` owns the collection's lifecycle, because a QE collection `MongoQueryableEncryptionCollectionManager`가 collection의 생성부터 삭제까지를 맡는다. QE collection은
is not just a collection: it carries metadata collections. collection 하나로 끝나지 않고 metadata collection을 같이 달고 다니기 때문이다.
## 3. Metadata ownership ## 3. Metadata 소유
`MongoEncryptionMetadataOwnership` maps `customers` to `enxcol_.customers.esc` and `MongoEncryptionMetadataOwnership`은 `customers`를 `enxcol_.customers.esc`와
`enxcol_.customers.ecoc`, and reports `__safeContent__`-prefixed indexes as `enxcol_.customers.ecoc`에 대응시킨다. 그리고 `__safeContent__`로 시작하는 index를
`MongoMetadataOwnership.ENCRYPTION_MANAGED`. `MongoMetadataOwnership.ENCRYPTION_MANAGED`로 보고한다.
These are never application-owned and never droppable by drift reconciliation. A drift tool that 이것들은 애플리케이션 소유가 아니다. drift 정리(선언과 실제의 차이를 맞추는 작업)가 지울 수도 없다.
drops `enxcol_.customers.ecoc` corrupts the collection's queryability. This is the single most drift 도구가 `enxcol_.customers.ecoc`를 지우면 그 collection은 조회 능력을 잃는다. 암호화와
important integration point between encryption and [ADR-MONGO-004](../../adr/ADR-MONGO-004-index-schema-admin-plane.md)가 만나는 곳 중 가장 중요한 지점이다.
[ADR-MONGO-004](../../adr/ADR-MONGO-004-index-schema-admin-plane.md).
## 4. Unsupported combinations ## 4. 지원하지 않는 조합
Refused at declaration, not discovered at runtime: 실행 중에 발견하지 않고 선언할 때 거부한다.
| Combination | Why | | 조합 | 이유 |
|---|---| |---|---|
| CSFLE **and** QE on the same collection | Two incompatible encryption schemes over one namespace. Both profile constructors refuse it. | | 같은 collection에 CSFLE **와** QE | namespace 하나에 서로 맞지 않는 암호화 방식 둘이다. 두 profile 생성자가 모두 거부한다. |
| CSFLE on a time series collection | `requireNotTimeSeries(true)` raises `MongoOperationRejectedException`. | | time series collection에 CSFLE | `requireNotTimeSeries(true)`가 `MongoOperationRejectedException`을 던진다. |
| QE `prefix` / `suffix` / `substring` | Not available on the platform's 8.0 baseline. The factory methods throw `UnsupportedOperationException` rather than returning a profile that fails later. | | QE `prefix` / `suffix` / `substring` | 플랫폼의 8.0 기준에서 쓸 수 없다. factory 메서드가 나중에 실패할 profile을 돌려주지 않고 바로 `UnsupportedOperationException`을 던진다. |
| Deterministic CSFLE without a justification | `IllegalArgumentException` naming frequency analysis. | | 근거 없는 deterministic CSFLE | 빈도 분석을 이유로 든 `IllegalArgumentException`. |
| Range QE without a declared domain | `IllegalArgumentException` naming re-encryption. | | 범위를 선언하지 않은 range QE | 재암호화를 이유로 든 `IllegalArgumentException`. |
## 5. Failure recovery ## 5. 실패 복구
| Symptom | Cause | Action | | 증상 | 원인 | 조치 |
|---|---|---| |---|---|---|
| `MongoEncryptionException` on read | Wrong data key, or the key vault is unreachable | Check KMS reachability and the key vault credential. Data is intact; the client cannot decrypt it. | | 읽을 때 `MongoEncryptionException` | data key가 틀렸거나 key vault에 닿지 못한다 | KMS 연결과 key vault credential을 확인한다. 데이터는 그대로다. client가 복호화하지 못할 뿐이다. |
| `MongoEncryptionException` on write | KMS permission revoked mid-operation | Restore the grant. Writes fail closed — nothing was written in plaintext. | | 쓸 때 `MongoEncryptionException` | 작업 도중 KMS 권한이 회수됐다 | 권한을 되돌린다. 쓰기는 닫힌 쪽으로 실패한다. 평문으로 쓴 것은 없다. |
| Queries return nothing on a deterministic field | The field was re-keyed | Equality matching is over ciphertext; a new key produces different ciphertext. Re-encrypt the field. | | deterministic 필드 조회가 아무것도 돌려주지 않는다 | 필드의 key를 바꿨다 | 같음 비교는 암호문끼리 한다. 새 key는 다른 암호문을 만든다. 필드를 다시 암호화한다. |
| QE queries fail after a drift reconciliation | A metadata collection was dropped | Restore from backup. This is why ownership gates drops. | | drift 정리 뒤 QE 조회가 실패한다 | metadata collection이 지워졌다 | 백업에서 복구한다. 그래서 삭제를 소유 여부로 막는다. |
**Key rotation.** Rotating the customer master key re-wraps the data keys and does not require **key 교체.** customer master key를 바꾸면 data key를 다시 감쌀 뿐이고 문서를 다시 암호화하지 않는다.
re-encrypting documents. Rotating a *data* key does require re-encrypting every document that used *data* key를 바꾸면 그 key를 쓴 문서를 모두 다시 암호화해야 한다. 둘은 비용이 다른 별개의 작업이다.
it. These are different operations with different costs, and confusing them is how a rotation becomes 둘을 헷갈리면 key 교체가 장애가 된다.
an outage.
## 6. Promotion evidence ## 6. 승격 증거
Per [ADR-MONGO-ADV-001](../../adr/ADR-MONGO-ADV-001-capability-promotion.md), promotion requires the [ADR-MONGO-ADV-001](../../adr/ADR-MONGO-ADV-001-capability-promotion.md)에 따라 승격하려면 실제 KMS와
real KMS and key vault, plus negative cases that fail closed: wrong key, missing permission, rotation key vault가 필요하다. 닫힌 쪽으로 실패하는 부정 사례도 필요하다: 틀린 key, 빠진 권한, 작업 도중 key 교체.
mid-operation. A local key provider certifies 로컬 key provider는 이 중 아무것도 인증하지 못한다. 아무것도 거부하지 않기 때문이다.
none of these — it never rejects anything.
+61 -65
View File
@@ -1,93 +1,89 @@
# Advanced — Multi-tenancy # Advanced — Multi-tenancy
**Capabilities:** `MongoCapability.SHARED_COLLECTION_TENANCY` (Advanced), **Capability:** `MongoCapability.SHARED_COLLECTION_TENANCY`(Advanced),
`MongoCapability.DATABASE_PER_TENANT` (Experimental) `MongoCapability.DATABASE_PER_TENANT`(Experimental)
**Enablement:** library API, no configuration property. The service's own adapter constructs the **켜는 법:** 라이브러리 API다. 설정 속성은 없다. 서비스의 어댑터가 진입점을 만들 때
entry point with a `MongoAdvancedCapabilityGuard` built from `MongoAdvancedCapabilityFlags` that `MongoAdvancedCapabilityGuard`를 넘긴다. 이 guard는 그 capability를 켠 `MongoAdvancedCapabilityFlags`로
enables the capability; construction is refused otherwise. 만든다. 켜지 않았으면 생성 자체가 거부된다.
Shared-collection tenancy has no entry point (its types are policies), so only shared collection tenancy에는 진입점이 없다(타입이 모두 정책이다). 그래서 실제로 검사하는 것은
`DATABASE_PER_TENANT` is ever checked. `DATABASE_PER_TENANT`뿐이다.
## 1. Shared collection ## 1. Shared collection
Every tenant's documents live in one collection, discriminated by a tenant field. 모든 tenant의 문서가 collection 하나에 있고, tenant 필드로 구분한다.
`MongoTenantContext` carries the tenant. `MongoTenantPredicateInjector` adds the tenant predicate to `MongoTenantContext`가 tenant를 들고 다닌다. `MongoTenantPredicateInjector`가 tenant 조건을 세 곳에
every query, every atomic filter and the **first** aggregation stage. The adopter's repository calls 넣는다: 모든 query, 모든 atomic filter, aggregation의 **첫** stage. 도입하는 쪽의 repository가 tenant
the injector on every tenant-scoped path; there is no tenant-scoped operations facade in this leaf. 범위의 모든 경로에서 이 injector를 부른다. 이 leaf에는 tenant 범위 작업을 대신해 주는 facade가 없다.
Three details are load-bearing: 빠지면 안 되는 세부가 셋이다.
- **Injection, not convention.** A tenant predicate that each query is expected to add itself is a - **관례가 아니라 주입이다.** query마다 tenant 조건을 스스로 넣기를 기대하면 `where(...)` 하나만 빠져도
cross-tenant leak waiting for one missed `where(...)`. The injector adds it structurally. tenant 사이로 데이터가 샌다. injector는 조건을 구조적으로 넣는다.
- **First aggregation stage.** `firstStageMatch(...)` places the tenant `$match` before anything else. - **aggregation 첫 stage.** `firstStageMatch(...)`는 tenant `$match`를 맨 앞에 둔다. tenant filter보다
A `$lookup` or `$group` that runs before the tenant filter has already crossed the boundary, even if 먼저 도는 `$lookup`이나 `$group`은 뒤 stage가 결과를 걸러도 이미 경계를 넘은 것이다.
a later stage filters the output. - **tenant가 없으면 「모든 tenant」가 아니다.** injector는 `Optional<MongoTenantContext>`를 받는다.
- **An absent tenant is not "all tenants".** The injector takes an `Optional<MongoTenantContext>` so tenant가 빠진 경우를 정책이 명시적으로 정하게 하려는 것이다. 조건이 조용히 사라지면 안 된다.
the missing case is a decision the policy makes explicitly, not a predicate that quietly disappears.
`MongoTenantManifestValidator.validate(manifest, tenantScopedUniqueIndexes)` checks that every unique `MongoTenantManifestValidator.validate(manifest, tenantScopedUniqueIndexes)`는 tenant별이어야 하는 unique
index that should be per-tenant actually includes the tenant field. A unique index on `email` alone in index가 정말 tenant 필드를 포함하는지 본다. shared collection에서 `email` 하나만으로 만든 unique index는
a shared collection makes an email globally unique across tenants — tenant B cannot register an email을 모든 tenant에 걸쳐 유일하게 만든다. 그러면 tenant A가 쓴 주소를 tenant B가 등록할 수 없다.
address tenant A already used, which is both a bug and an information leak. 결함이면서 정보 유출이다.
`requireShardKeyAnalysed(...)` requires a shard-key readiness report before a shared-collection tenant `requireShardKeyAnalysed(...)`는 shared collection tenant 모델을 shard하기 전에 shard key 준비 보고서를
model is sharded: tenant id as a shard key prefix concentrates the largest tenant on one shard. 요구한다. tenant id를 shard key 앞부분으로 쓰면 가장 큰 tenant가 shard 하나에 몰린다.
### Observability ### 관측
`tenantId` and `rawTenantId` are on `MongoObservationConvention`'s forbidden tag list. Cardinality `tenantId`와 `rawTenantId`는 `MongoObservationConvention`의 금지 tag 목록에 있다. 값의 가짓수가 고객
grows with the customer list, and the tag ships tenant identity into the metrics backend. 수만큼 늘고, tag가 tenant 식별자를 metric 저장소로 보낸다.
## 2. Database per tenant (Experimental) ## 2. tenant마다 database (Experimental)
`MongoTenantClientRegistry` holds one client per tenant under a cap with idle eviction; mapping a `MongoTenantClientRegistry`는 tenant마다 client를 하나 둔다. 개수 상한이 있고 쓰지 않는 client는
tenant to its database is the adopter's code. 내보낸다. tenant를 어느 database에 대응시킬지는 도입하는 쪽의 코드가 정한다.
Experimental for a specific reason: it is correct in the small and unbounded in the large. Each tenant Experimental인 이유가 분명하다. 작을 때는 맞고, 클 때는 한계가 없다. tenant database마다 connection,
database costs connections, file handles and monitoring cardinality. It works beautifully at 20 file handle, 모니터링 가짓수가 든다. tenant 20개에서는 잘 돌고 2,000개에서는 쓰러진다. 기능 테스트로는
tenants and falls over at 2,000, and nothing in a functional test distinguishes the two. Promotion 둘을 구분할 수 없다. 승격하려면 운영 규모의 증거가 필요하다.
requires operational scale evidence.
`MongoTenantLifecyclePolicy`: `MongoTenantLifecyclePolicy`:
- `requireActivationReady(tenantKey, schemaAndIndexesValidated)` — a tenant is not activated until its - `requireActivationReady(tenantKey, schemaAndIndexesValidated)` — schema와 index를 검증하기 전에는
schema and indexes are validated. Activating first means the first customer request is the migration tenant를 켜지 않는다. 먼저 켜면 첫 고객 요청이 마이그레이션 시험이 된다.
test. - `requireDeleteAllowed(...)` — 삭제에는 보존 기간에 대한 명시적 결정이 필요하다. tenant database를 지우면
- `requireDeleteAllowed(...)` — deletion requires an explicit retention decision. Dropping a tenant 되돌릴 수 없고 백업 대상도 함께 사라진다.
database is irreversible and takes the backup surface with it.
`MongoTenantMigrationCoordinator` runs a migration across tenant databases with per-tenant results. `MongoTenantMigrationCoordinator`는 tenant database 전체에 마이그레이션을 돌리고 결과를 tenant별로 낸다.
Partial failure is normal and must be reported per tenant: "migration failed" across 500 databases is 일부 실패는 정상이고 tenant별로 보고해야 한다. database 500개에 대해 「마이그레이션 실패」 한 줄은 아무도
not a report anyone can act on. 대응할 수 없는 보고다.
## 3. Choosing ## 3. 고르기
| | Shared collection | Database per tenant | | | Shared collection | tenant마다 database |
|---|---|---| |---|---|---|
| Isolation | Logical, enforced by injection | Physical | | 격리 | 논리적, 주입으로 강제 | 물리적 |
| Tenant count | Unbounded | Bounded by connections and file handles | | tenant 수 | 제한 없음 | connection과 file handle이 제한 |
| Per-tenant restore | Hard | Natural | | tenant별 복구 | 어렵다 | 자연스럽다 |
| Noisy neighbour | Shared resources | Isolated | | 시끄러운 이웃 | 자원을 나눠 쓴다 | 격리된다 |
| Migration | One collection | N databases, partial failures | | 마이그레이션 | collection 하나 | database N개, 일부 실패가 생긴다 |
| Cross-tenant query | Possible (and must be forbidden) | Structurally impossible | | tenant를 넘는 query | 가능하다(그래서 막아야 한다) | 구조상 불가능하다 |
Shared collection is the default. Database-per-tenant is for a small number of tenants with a 기본은 shared collection이다. tenant마다 database는 tenant 수가 적고, 계약상 격리나 tenant별 복구가
contractual isolation or per-tenant-restore requirement. 필요한 경우에 쓴다.
## 4. Failure recovery ## 4. 실패 복구
| Symptom | Cause | Action | | 증상 | 원인 | 조치 |
|---|---|---| |---|---|---|
| Cross-tenant data visible | An operation skipped `MongoTenantPredicateInjector` | Treat as a security incident. Find the path, close it, audit access. | | 다른 tenant의 데이터가 보인다 | 어떤 작업이 `MongoTenantPredicateInjector`를 건너뛰었다 | 보안 사고로 다룬다. 그 경로를 찾아 막고 접근 기록을 감사한다. |
| Unique constraint fires across tenants | Unique index missing the tenant field | Rebuild the index with the tenant field as prefix; the validator catches this before it ships. | | tenant를 넘어 unique 제약이 걸린다 | unique index에 tenant 필드가 없다 | tenant 필드를 앞에 둔 index로 다시 만든다. validator가 배포 전에 잡는다. |
| One shard holds most data | Tenant id as shard-key prefix with a dominant tenant | Refine the shard key with a high-cardinality suffix. | | shard 하나에 데이터 대부분이 있다 | tenant id가 shard key 앞부분이고 큰 tenant가 하나 있다 | 가짓수가 많은 뒷부분을 더해 shard key를 다듬는다. |
| Connection exhaustion | Database-per-tenant beyond the connection budget | The scale limit. Consolidate or move to shared collections. | | connection이 바닥난다 | tenant마다 database가 connection 예산을 넘었다 | 규모 한계다. 합치거나 shared collection으로 옮긴다. |
| Migration partially applied across tenants | Normal | `MongoTenantMigrationCoordinator` reports per tenant; re-run for the failures only. | | 마이그레이션이 tenant 일부에만 적용됐다 | 정상이다 | `MongoTenantMigrationCoordinator`가 tenant별로 보고한다. 실패한 것만 다시 돌린다. |
## 5. Promotion evidence ## 5. 승격 증거
Shared-collection tenancy: actual-topology evidence, a security review covering cross-tenant access, shared collection tenancy: 실제 토폴로지 증거, tenant를 넘는 접근을 다룬 보안 검토, 마이그레이션 경로,
a migration path, failure cases (injection proven on query, atomic filter and first aggregation 실패 사례(query·atomic filter·aggregation 첫 stage에서 주입이 되는지 증명), 이 runbook.
stage), this runbook. Database-per-tenant additionally requires **operational scale evidence** and tenant마다 database는 여기에 **운영 규모 증거**가 더 필요하고, 그것이 생길 때까지 Experimental이다.
stays Experimental until it exists.
+50 -54
View File
@@ -1,84 +1,80 @@
# Advanced — Sharding # Advanced — Sharding
**Capability:** `MongoCapability.SHARDING` **Capability:** `MongoCapability.SHARDING`
**Enablement:** library API, no configuration property. The service's own adapter constructs the **켜는 법:** 라이브러리 API다. 설정 속성은 없다. 서비스의 어댑터가 진입점을 만들 때
entry point with a `MongoAdvancedCapabilityGuard` built from `MongoAdvancedCapabilityFlags` that `MongoAdvancedCapabilityGuard`를 넘긴다. 이 guard는 그 capability를 켠 `MongoAdvancedCapabilityFlags`로
enables the capability; construction is refused otherwise. 만든다. 켜지 않았으면 생성 자체가 거부된다.
**Status:** Advanced. Reshard orchestration remains Experimental. **상태:** Advanced. reshard 진행 관리는 Experimental로 남는다.
## Requirements ## 요구 사항
| | | | | |
|---|---| |---|---|
| Topology | A real sharded cluster. A replica set cannot exercise routing. | | 토폴로지 | 실제 sharded cluster. replica set으로는 라우팅을 시험할 수 없다. |
| Server | MongoDB 7.0 or 8.0. | | 서버 | MongoDB 7.0 또는 8.0. |
| Privilege | `MongoPrincipalRole.SHARD_ADMIN` for the admin plane; the application role is unchanged. | | 권한 | admin plane에는 `MongoPrincipalRole.SHARD_ADMIN`. 애플리케이션 role은 바뀌지 않는다. |
| Gate | **Not promoted.** No `mongoShardedTest` lane is registered, and a sharded cluster is not an environment this repository stands up. Listed under `experimental_contracts` in `src/adapter/outbound/persistence-mongo/release/release-contracts.json`; promoting it needs the lane, its required class, and protected-environment evidence to exist first. | | 게이트 | **승격하지 않았다.** 등록된 `mongoShardedTest` lane이 없고, sharded cluster는 이 repo가 띄우는 환경이 아니다. `src/adapter/outbound/persistence-mongo/release/release-contracts.json`의 `experimental_contracts`에 있다. 승격하려면 lane, 그 lane이 요구하는 클래스, 보호된 환경의 증거가 먼저 있어야 한다. |
## Shard key ## Shard key
`ShardKeyDescriptor` declares the key as an ordered list of `ShardKeyPart` plus a `ShardStrategy`: `ShardKeyDescriptor`는 key를 `ShardKeyPart`의 순서 있는 목록과 `ShardStrategy`로 선언한다.
| Strategy | Distributes | Cost | | 전략 | 나누는 기준 | 비용 |
|---|---|---| |---|---|---|
| `RANGE` | by value ranges | Range queries stay targeted; a monotonic key (a timestamp, an `ObjectId`) sends every insert to one shard. | | `RANGE` | 값의 범위 | 범위 조회가 특정 shard로 간다. 계속 커지는 key(timestamp, `ObjectId`)는 모든 insert를 shard 하나로 보낸다. |
| `HASHED` | by hash of the key | Inserts spread evenly; every range query becomes scatter-gather. | | `HASHED` | key의 hash | insert가 고르게 퍼진다. 모든 범위 조회가 scatter-gather가 된다. |
There is no strategy that is good at both, which is why the choice is a declaration rather than a 둘 다 잘하는 전략은 없다. 그래서 기본값으로 두지 않고 선언하게 한다.
default.
## Routing classification ## 라우팅 분류
`ShardAwareQueryValidator` classifies each query before execution: `ShardAwareQueryValidator`는 실행 전에 query마다 분류한다.
| `MongoRoutingClassification` | Meaning | | `MongoRoutingClassification` | 뜻 |
|---|---| |---|---|
| `TARGETED` | The full shard key is present. One shard answers. | | `TARGETED` | shard key 전체가 있다. shard 하나가 답한다. |
| `PREFIX_TARGETED` | A prefix of a compound key is present. A subset of shards answers. | | `PREFIX_TARGETED` | 복합 key의 앞부분이 있다. shard 일부가 답한다. |
| `SCATTER_GATHER` | No shard-key predicate. Every shard answers. | | `SCATTER_GATHER` | shard key 조건이 없다. 모든 shard가 답한다. |
| `REJECTED` | Scatter-gather where the profile forbids it. | | `REJECTED` | profile이 금지한 곳의 scatter-gather. |
A scatter-gather query is not an error — some queries legitimately need every shard — but it must be scatter-gather는 오류가 아니다. 모든 shard가 필요한 query도 있다. 다만 선언해야 한다. 선언하지 않은
declared. Undeclared scatter-gather raises `MongoShardRoutingException`. The reason is that scatter-gather는 `MongoShardRoutingException`을 던진다. 이유는 이렇다. scatter-gather는 shard 하나짜리
scatter-gather passes every test on a single-shard development cluster and only degrades once the 개발 cluster에서는 모든 테스트를 통과하고 cluster가 커진 뒤에야 느려진다. 그때는 query가 이미 운영에
cluster grows, at which point the query is already in production and the fix is a schema change. 있고, 고치려면 schema를 바꿔야 한다.
## Unsupported combinations ## 지원하지 않는 조합
- Unique index on a field that is not a prefix of the shard key. MongoDB cannot enforce it across - shard key의 앞부분이 아닌 필드의 unique index. MongoDB가 shard를 넘어 강제할 수 없다. 조회 때가
shards, and it fails at index creation, not at query time. 아니라 index를 만들 때 실패한다.
- Transactions that touch documents on multiple shards remain supported but cost a cross-shard - 여러 shard의 문서를 건드리는 transaction은 지원하지만 shard를 넘는 two-phase commit 비용이 든다.
two-phase commit. Prefer a shard key that keeps a transaction's documents co-located. transaction의 문서를 한곳에 모으는 shard key를 고른다.
- CSFLE on a sharded collection: see [encryption.md](encryption.md) for the combinations that are - sharded collection의 CSFLE: 거부하는 조합은 [encryption.md](encryption.md)를 본다.
refused.
## Admin plane ## Admin plane
`MongoShardingAdminGateway` (D4, `SHARD_ADMIN` credential) covers shard-collection, refine-shard-key `MongoShardingAdminGateway`(D4, `SHARD_ADMIN` credential)가 shard-collection, refine-shard-key,
and reshard. reshard를 맡는다.
`ShardKeyAnalyzer` produces a `ShardKeyReadinessReport` before sharding a collection: cardinality, `ShardKeyAnalyzer`는 collection을 shard하기 전에 `ShardKeyReadinessReport`를 만든다: 값의 가짓수,
frequency skew and monotonicity. A key with low cardinality creates jumbo chunks that cannot be split; 빈도 치우침, 단조 증가 여부. 가짓수가 적은 key는 나눌 수 없는 jumbo chunk를 만든다. 단조 증가하는
a monotonic key creates a hot shard. Both are visible in the report and invisible in a functional key는 한 shard에 부하를 몰아준다. 둘 다 보고서에는 보이고 기능 테스트에는 보이지 않는다.
test.
`ReshardApproval` is required for a reshard — a named approver and a stated window. Resharding reshard에는 `ReshardApproval`이 필요하다: 승인한 사람 이름과 작업 시간대. reshard는 collection을 다시
rewrites the collection: it duplicates the data during the operation and saturates IO. It is not a 쓴다. 작업 중에 데이터를 복제하고 IO를 가득 채운다. 실행 중에 하는 작업이 아니고, 타입도 그런 척하지
runtime operation and the type refuses to pretend otherwise. 않는다.
## Failure recovery ## 실패 복구
| Symptom | Cause | Action | | 증상 | 원인 | 조치 |
|---|---|---| |---|---|---|
| `MongoShardRoutingException` | Undeclared scatter-gather | Add the shard key to the predicate, or declare the query as scatter-gather in its profile after review. | | `MongoShardRoutingException` | 선언하지 않은 scatter-gather | 조건에 shard key를 넣는다. 아니면 검토를 거쳐 그 query를 profile에서 scatter-gather로 선언한다. |
| Jumbo chunks | Low-cardinality shard key | Refine the shard key (adds a suffix, non-destructive) before considering a reshard. | | Jumbo chunk | 가짓수가 적은 shard key | reshard를 생각하기 전에 shard key를 다듬는다(뒷부분을 더한다. 데이터를 지우지 않는다). |
| One hot shard | Monotonic range key | Refine with a high-cardinality prefix, or reshard to hashed if range queries are not needed. | | 한 shard에 부하가 몰린다 | 단조 증가하는 range key | 가짓수가 많은 앞부분으로 다듬거나, 범위 조회가 필요 없으면 hashed로 reshard한다. |
| Balancer never converges | Chunk migration blocked by long-running operations | Check for long transactions and cursors; the balancer waits on them. | | balancer가 끝나지 않는다 | 오래 도는 작업이 chunk 이동을 막는다 | 긴 transaction과 cursor를 찾는다. balancer는 그것들을 기다린다. |
## Promotion evidence ## 승격 증거
Per [ADR-MONGO-ADV-001](../../adr/ADR-MONGO-ADV-001-capability-promotion.md): actual sharded-cluster [ADR-MONGO-ADV-001](../../adr/ADR-MONGO-ADV-001-capability-promotion.md)에 따라: 실제 sharded cluster
evidence, security review of the `SHARD_ADMIN` role, a migration path for an existing unsharded 증거, `SHARD_ADMIN` role의 보안 검토, 이미 있는 unsharded collection의 마이그레이션 경로, 실패 사례(선언하지
collection, failure cases (undeclared scatter-gather refused, jumbo chunk detected), and this 않은 scatter-gather 거부, jumbo chunk 감지), 그리고 runbook으로서 이 문서. reshard 진행 관리는 운영
document as the runbook. Reshard orchestration stays Experimental until operational scale evidence 규모 증거가 생길 때까지 Experimental이다.
exists.
+11 -13
View File
@@ -1,18 +1,16 @@
# Advanced capability sign-off # Advanced capability 검토 기록(sign-off)
> **2026-08-15:** `scripts/verify-mongodb-advanced.sh` was removed, so nothing reads this directory `scripts/verify-mongodb-advanced.sh`는 이 디렉터리의 파일을 검토가 있었다는 증거로 본다.
> automatically any more. The files below are still the record that a review happened, but a missing
> one no longer fails anything — a human has to check for it during promotion.
`scripts/verify-mongodb-advanced.sh` treated a file in this directory as the evidence that a review - `security.md` — capability별 권한 검토. 부여한 role과 부여한 사람을 적는다.
happened: - `migration.md` — capability별 마이그레이션 경로. 이미 있는 배포가 무엇을 해야 하는지 적는다.
- `security.md` — per-capability privilege review, naming the roles granted and by whom. 둘 중 하나가 없으면 스크립트는 그 항목을 빠진 증거로 적고 `ADVANCED GATE: NOT PROMOTABLE`로 끝난다
- `migration.md` — per-capability migration path, naming what an existing deployment has to do. (종료 코드 2). 실패(종료 코드 1)로 보지는 않는다.
These were previously appended to the gate's missing-evidence list unconditionally, so the gate had 예전에는 이 둘을 조건 없이 빠진 증거 목록에 넣었다. 그래서 게이트가 통과할 수 있는 상태가 아예 없었다.
no passing state at all. A gate that can never pass is one nobody can act on, and the thing it was 절대 통과할 수 없는 게이트는 아무도 대응할 수 없다. 게이트가 기다리던 것, 곧 사람의 검토에는 남는
waiting for — a human review — has an artefact. This is that artefact. 결과물이 있다. 이 디렉터리의 파일이 그 결과물이다.
A file here asserts the review was done. Adding one without doing it is the failure mode; that is a 여기 있는 파일은 검토를 했다고 주장한다. 검토 없이 파일만 더하는 것이 이 방식의 실패 모드다. 그것은
review-process problem, and no script can tell the difference. 검토 절차의 문제이고, 어떤 스크립트도 차이를 알 수 없다.
+50 -53
View File
@@ -1,75 +1,72 @@
# BSON Mapping Guide # BSON 매핑 가이드
Design §10 and decision D-06. The representation of a value in BSON is a data contract, not an 설계서 §10과 결정 D-06. 값이 BSON에서 어떤 모양으로 저장되는지는 구현 세부가 아니라 데이터 계약이다.
implementation detail: once a collection holds a million documents, changing how a `BigDecimal` is collection에 문서가 백만 개 쌓인 뒤 `BigDecimal` 저장 방식을 바꾸면 코드 수정이 아니라 중단 시간이 드는
stored is a migration with downtime, not a code change. `MongoTypeRepresentationManifest` pins the 마이그레이션이다. `MongoTypeRepresentationManifest`가 표현을 고정해서 라이브러리 업그레이드나 다른
representation so a library upgrade or a different default cannot move it. 기본값이 그것을 바꾸지 못하게 한다.
## 1. The manifest ## 1. Manifest
`MongoTypeRepresentationManifest.standard()` fixes: `MongoTypeRepresentationManifest.standard()`가 정하는 것:
| Java type | BSON | Representation type | | Java 타입 | BSON | 표현 타입 |
|---|---|---| |---|---|---|
| `UUID` | `Binary` subtype 4 | `MongoUuidRepresentation.STANDARD` | | `UUID` | `Binary` subtype 4 | `MongoUuidRepresentation.STANDARD` |
| `BigDecimal` | `Decimal128` | `MongoDecimalRepresentation.DECIMAL_128` | | `BigDecimal` | `Decimal128` | `MongoDecimalRepresentation.DECIMAL_128` |
| `BigInteger` | `Decimal128` (or `String` when out of range, declared) | `MongoBigIntegerRepresentation` | | `BigInteger` | `Decimal128`(범위를 넘으면 선언한 경우 `String`) | `MongoBigIntegerRepresentation` |
| `Instant` / `OffsetDateTime` / `ZonedDateTime` | UTC `Date` | `MongoTemporalRepresentation.UTC_DATE` | | `Instant` / `OffsetDateTime` / `ZonedDateTime` | UTC `Date` | `MongoTemporalRepresentation.UTC_DATE` |
| `LocalDate` | `String` (ISO-8601) or UTC `Date`, declared per field | `MongoTemporalRepresentation` | | `LocalDate` | `String`(ISO-8601) 또는 UTC `Date`, 필드마다 선언 | `MongoTemporalRepresentation` |
| `enum` | `String` name | `MongoEnumRepresentation.NAME` | | `enum` | `String` 이름 | `MongoEnumRepresentation.NAME` |
`MongoMappingConfiguration` and `MongoCustomConversionsFactory` build the Spring Data converters from `MongoMappingConfiguration`과 `MongoCustomConversionsFactory`가 이 manifest로 Spring Data converter를
the manifest, so there is one place to read and one place to change. 만든다. 그래서 읽을 곳도 한 곳, 바꿀 곳도 한 곳이다.
## 2. UUID ## 2. UUID
`UuidRepresentation.STANDARD` (subtype 4), always. The driver's legacy Java representation 늘 `UuidRepresentation.STANDARD`(subtype 4)다. driver의 옛 Java 표현(subtype 3)은 UUID의 두 절반의
(subtype 3) byte-swaps two halves of the UUID, so a document written by one representation and read 바이트 순서를 뒤집는다. 그래서 한 표현으로 쓴 문서를 다른 표현으로 읽으면 다르면서도 멀쩡해 보이는
by the other yields a different — and valid-looking — UUID. Nothing errors; you just get the wrong UUID가 나온다. 오류는 나지 않고 엉뚱한 행을 얻는다. 같은 이유로 golden snapshot kit은 codec을
row. The golden snapshot kit pins the codec explicitly for this reason 명시적으로 고정한다(`MongoBsonSnapshot.defaultRegistry()`).
(`MongoBsonSnapshot.defaultRegistry()`).
## 3. Decimal ## 3. Decimal
`BigDecimal` → `Decimal128`, never `Double`. `12.30` stored as a double is `12.299999999999999`, and `BigDecimal` → `Decimal128`이다. `Double`은 쓰지 않는다. `12.30`을 double로 저장하면
a monetary comparison written against it will one day be wrong by a cent for a customer who notices. `12.299999999999999`가 된다. 그 값으로 쓴 금액 비교는 언젠가 1원 틀리고, 그것을 알아채는 고객이 있다.
`BigDecimalToDecimal128Converter` / `Decimal128ToBigDecimalConverter` are registered from the `BigDecimalToDecimal128Converter` / `Decimal128ToBigDecimalConverter`는 manifest에서 등록한다.
manifest.
`Decimal128` has 34 significant digits; a `BigDecimal` beyond that range fails on write rather than `Decimal128`의 유효 숫자는 34자리다. 그 범위를 넘는 `BigDecimal`은 조용히 반올림하지 않고 쓸 때 실패한다.
rounding silently.
## 4. Time ## 4. 시간
Store instants, not local times. `LocalDateTimeMappingGuard` refuses `LocalDateTime` fields on a 지역 시각이 아니라 순간(instant)을 저장한다. `LocalDateTimeMappingGuard`는 매핑된 문서의
mapped document: a `LocalDateTime` has no offset, so the value that goes in depends on the JVM `LocalDateTime` 필드를 거부한다. `LocalDateTime`에는 offset이 없다. 그래서 저장되는 값이 그 값을 쓴
default zone of whichever instance wrote it, and the two instances in a rolling deploy can disagree. 인스턴스의 JVM 기본 시간대에 따라 달라지고, rolling 배포 중인 두 인스턴스의 값이 어긋날 수 있다.
Use `Instant` when the moment matters and `LocalDate` when the calendar day matters. 순간이 중요하면 `Instant`를, 달력의 날짜가 중요하면 `LocalDate`를 쓴다.
## 5. Type metadata ## 5. 타입 metadata
`MongoTypeMetadataPolicy` decides what goes in `_class`: `MongoTypeMetadataPolicy`가 `_class`에 무엇을 넣을지 정한다.
| Policy | Stored | Use when | | 정책 | 저장하는 것 | 쓰는 때 |
|---|---|---| |---|---|---|
| `NONE` | nothing | The collection holds exactly one type and never will hold a subtype. | | `NONE` | 없음 | collection에 타입이 정확히 하나이고 앞으로도 하위 타입이 들어오지 않는다. |
| `ALIAS` | a registered short alias | A polymorphic hierarchy in a long-lived collection. | | `ALIAS` | 등록한 짧은 별칭 | 오래 사는 collection의 다형 계층. |
| `CLASS_NAME` | the FQCN | Short-lived or internal collections only. | | `CLASS_NAME` | FQCN | 짧게 사는 collection이나 내부 collection에만. |
`PolicyAwareMongoTypeMapper` enforces it, and `MongoTypeMetadataRegistry` holds alias → class. `PolicyAwareMongoTypeMapper`가 이 정책을 강제하고, `MongoTypeMetadataRegistry`가 별칭 → 클래스를
A `@LongLivedMongoDocument` type with `CLASS_NAME` is refused: writing `com.example.OrderV2` into a 가진다. `@LongLivedMongoDocument` 타입에 `CLASS_NAME`을 쓰면 거부한다. 문서 백만 개에
million documents means that renaming the package is a data migration. `com.example.OrderV2`를 써 두면 package 이름을 바꾸는 일이 데이터 마이그레이션이 된다.
## 6. Missing versus null ## 6. 없음과 null
The golden kit keeps these apart deliberately. `MongoBsonSnapshotAssert.hasNoField(...)` and golden kit은 이 둘을 일부러 구분한다. `MongoBsonSnapshotAssert.hasNoField(...)`와
`hasExplicitNull(...)` are different assertions, because in MongoDB they are different documents: `hasExplicitNull(...)`은 다른 단언이다. MongoDB에서 둘은 다른 문서이기 때문이다.
`{"a": null}` matches `{a: null}` and `{a: {$exists: true}}`, while `{}` matches only the first. `{"a": null}`은 `{a: null}`과 `{a: {$exists: true}}`에 모두 걸리지만 `{}`는 앞의 것에만 걸린다.
A mapper change that starts writing explicit nulls silently changes what your queries return. mapper가 바뀌어 null을 명시적으로 쓰기 시작하면 query 결과가 조용히 달라진다.
## 7. Golden representation tests ## 7. Golden 표현 테스트
Every collection with a fixed representation should have a snapshot test: 표현이 고정된 collection에는 snapshot 테스트를 둔다.
```java ```java
MongoBsonSnapshot snapshot = MongoBsonSnapshot.of(storedDocument); MongoBsonSnapshot snapshot = MongoBsonSnapshot.of(storedDocument);
@@ -80,13 +77,13 @@ MongoBsonSnapshotAssert.assertThat(snapshot)
.hasTypeSignature("_id:OBJECT_ID,amount:DECIMAL128,createdAt:DATE_TIME,externalId:BINARY"); .hasTypeSignature("_id:OBJECT_ID,amount:DECIMAL128,createdAt:DATE_TIME,externalId:BINARY");
``` ```
`hasTypeSignature` is the regression gate: it fails on *any* representation change, including ones a `hasTypeSignature`가 회귀 게이트다. 값이 같은지만 보는 단언이 통과시킬 변화까지 포함해 *어떤* 표현
value-equality assertion would pass. When it fails, the question is whether the change was intended 변화에도 실패한다. 실패하면 물을 것은 문자열을 고칠지가 아니라, 그 변화가 의도한 것이고 마이그레이션이
and has a migration — not whether to update the string. 있는지다.
## 8. Round trips ## 8. 왕복
`MongoRoundTripContract` asserts that `write → read` returns an equal domain object *and* that `MongoRoundTripContract`는 두 가지를 단언한다. `write → read`가 같은 도메인 객체를 돌려준다. *그리고*
`write → read → write` produces an identical BSON document. The second half is what catches an `write → read → write`가 똑같은 BSON 문서를 만든다. 뒤의 것이 비대칭 converter를 잡는다. 읽으면 같지만
asymmetric converter: a value that reads back equal but re-serialises differently makes every 다시 직렬화하면 달라지는 값은 이후의 모든 `save()`를 쓸데없는 update로 만들고, change stream을 잡음
subsequent `save()` a spurious update, and turns change streams into a noise generator. 발생기로 만든다.
+78 -85
View File
@@ -1,67 +1,63 @@
# Consistency and Transaction Guide # 일관성과 transaction 가이드
Design §12–§16, decisions D-07 through D-10. This is the part of the platform where the wrong 설계서 §12–§16, 결정 D-07에서 D-10까지. 플랫폼에서 기본값을 잘못 고르면 가장 비싸고, 테스트에서는 가장
default is most expensive and the least visible in testing, because every failure mode here needs a 안 보이는 곳이다. 여기의 실패 모드는 모두 primary가 바뀌어야 재현되기 때문이다.
primary change to reproduce.
## 1. Prefer a single-document atomic operation ## 1. 문서 하나의 atomic 연산을 먼저 쓴다
D-09: a transaction is for a **multi-document invariant**, nothing else. A single document is already D-09: transaction은 **여러 문서에 걸친 불변식**에만 쓴다. MongoDB에서 문서 하나는 이미 atomic이다.
atomic in MongoDB, so wrapping a one-document update in a transaction buys nothing and costs a 문서 하나를 바꾸는 update를 transaction으로 감싸면 얻는 것은 없고, session 하나, two-phase commit,
session, a two-phase commit and a new ambiguous outcome. 결과를 모르는 새 경우 하나가 든다.
D-07: partial change uses update operators, not `save()`. `MongoAtomicOperations` / D-07: 일부만 바꿀 때는 `save()`가 아니라 update operator를 쓴다. `MongoAtomicOperations` /
`MongoAtomicOperationsTemplate` expose the operator set through `MongoUpdateOperator` `MongoAtomicOperationsTemplate`은 `MongoUpdateOperator`로 operator(`$set`, `$inc`, `$push`, `$pull`,
(`$set`, `$inc`, `$push`, `$pull`, `$addToSet`, `$min`, `$max`, `$currentDate`, …) with an `$addToSet`, `$min`, `$max`, `$currentDate`, …)를 내놓고, `AtomicFilter` 선행 조건과
`AtomicFilter` precondition and a `ReturnDocumentMode`. Read-modify-write through `save()` replaces `ReturnDocumentMode`를 받는다. `save()`로 읽고-고치고-쓰면 문서 전체를 바꾼다. 그 사이에 다른 쓰기가
the whole document and silently discards any field another writer changed in between — a lost update 바꾼 필드는 조용히 사라진다. 오류 없는 lost update다.
with no error.
## 2. Whole-document replacement needs a revision ## 2. 문서 전체를 바꾸려면 revision이 필요하다
D-08. `VersionedMongoUpdater` requires a `MongoRevision`: either a Spring Data `@Version` field or an D-08. `VersionedMongoUpdater`는 `MongoRevision`을 요구한다. Spring Data `@Version` 필드이거나,
explicit expected-revision predicate in `VersionedUpdateCommand`. A replacement whose filter matched `VersionedUpdateCommand` 안의 명시적인 기대 revision 조건이다. 교체 filter에 걸린 문서가 0개여도
zero documents is not "nothing to do" — `MongoOptimisticConflictTranslator` distinguishes: 「할 일 없음」이 아니다. `MongoOptimisticConflictTranslator`가 둘을 구분한다.
- filter matched nothing and the id does not exist → `MongoDocumentNotFoundException` - filter에 걸린 것이 없고 그 id가 없다 → `MongoDocumentNotFoundException`
- filter matched nothing and the id exists → `MongoOptimisticConflictException` - filter에 걸린 것이 없고 그 id가 있다 → `MongoOptimisticConflictException`
Collapsing these two into one is how a concurrent overwrite becomes a 404. 이 둘을 하나로 합치면 동시 덮어쓰기가 404가 된다.
## 3. Consistency profiles ## 3. 일관성 profile
`MongoConsistencyProfile` names the read/write concern pair; `MongoConsistencyRegistry` binds a `MongoConsistencyProfile`은 read/write concern 쌍에 이름을 붙인다. `MongoConsistencyRegistry`가 profile을
profile to an operation or collection, and `MongoConsistencyBinder` applies it at execution. 연산이나 collection에 묶고, `MongoConsistencyBinder`가 실행할 때 적용한다.
| Profile | Meaning | Use for | | Profile | 뜻 | 쓰는 곳 |
|---|---|---| |---|---|---|
| `PRIMARY_LOCAL` | primary read, local concern | Throughput-sensitive reads that tolerate a rollback window. | | `PRIMARY_LOCAL` | primary 읽기, local concern | rollback 구간을 견디는, 처리량이 중요한 읽기. |
| `PRIMARY_MAJORITY` | primary read, majority write | The default for anything a user will see again immediately. | | `PRIMARY_MAJORITY` | primary 읽기, majority 쓰기 | 사용자가 곧바로 다시 볼 모든 것의 기본값. |
| `CAUSAL_MAJORITY` | majority inside a causal session | Read-your-writes across separate operations. | | `CAUSAL_MAJORITY` | causal session 안의 majority | 따로 떨어진 연산 사이에서 자기가 쓴 것을 읽기. |
| `STALE_READ_ALLOWED` | secondary reads permitted | Reporting and analytics that state their staleness. | | `STALE_READ_ALLOWED` | secondary 읽기 허용 | 얼마나 낡았는지 밝히는 보고·분석. |
| `SNAPSHOT_TRANSACTION` | snapshot isolation | Multi-document reads inside a transaction. | | `SNAPSHOT_TRANSACTION` | snapshot 격리 | transaction 안의 여러 문서 읽기. |
A profile is a declaration, not a hint: the registry is consulted per operation and an operation profile은 힌트가 아니라 선언이다. registry는 연산마다 조회되고, profile을 등록하지 않은 연산은 기본값으로
without a registered profile is rejected rather than defaulting. 가지 않고 거부된다.
## 4. Causal sessions ## 4. Causal session
`MongoCausalSessionContext` plus `SpringMongoCausalSessionExecutor` carry the cluster time and `MongoCausalSessionContext`와 `SpringMongoCausalSessionExecutor`가 연산 사이에 cluster time과 operation
operation time between operations, so time을 옮긴다. 그래서 「쓰고 나서 읽기」가 다른 노드로 가도 쓴 값을 돌려받는다. causal session이 없으면
"write then read" returns the write even when the read lands on a different node. Without a causal `PRIMARY_MAJORITY`는 내구성은 주지만, 호출 두 번에 걸쳐 자기가 쓴 것을 읽는 것은 보장하지 않는다.
session, `PRIMARY_MAJORITY` gives you durability but not read-your-writes across two calls.
## 5. Transactions ## 5. Transaction
`MongoTransactionExecutor` opens a session through the session `MongoTransactionExecutor`는 session factory로 session을 열고, 본문을 돌리고, commit한다.
factory, run the body, and commit. `MongoTransactionProfile` carries the consistency profile, the `MongoTransactionProfile`은 일관성 profile, `maxCommitTime`, 재시도 예산을 가진다. 토폴로지가 중요하다.
`maxCommitTime` and the retry budget. Topology matters: a transaction requires a replica set, and transaction에는 replica set이 필요하다. `MongoStartupValidator`는 `STANDALONE`에서 transaction을 선언한
`MongoStartupValidator` refuses a transaction-declaring profile on `STANDALONE` at startup rather profile을 첫 호출이 아니라 시작할 때 거부한다.
than at the first call.
## 6. Retry: body and commit are different loops ## 6. 재시도: 본문과 commit은 다른 loop다
D-10, and the single most consequential rule in the design. D-10이고, 설계에서 결과가 가장 큰 규칙이다.
``` ```
for each body attempt: for each body attempt:
@@ -72,56 +68,53 @@ for each body attempt:
UnknownTransactionCommitResult -> retry COMMIT ONLY, same session UnknownTransactionCommitResult -> retry COMMIT ONLY, same session
``` ```
`MongoTransactionRetryCoordinator` implements exactly this: `MongoTransactionRetryCoordinator`가 정확히 이것을 구현한다.
- **A new session per body attempt.** Reusing the session after an abort carries the aborted - **본문 시도마다 새 session.** abort한 뒤 session을 다시 쓰면 abort한 transaction의 상태가 재시도로
transaction's state into the retry. 넘어간다.
- **The body is never replayed after a commit ambiguity.** An unknown commit means the commit may - **commit 결과를 모르면 본문을 다시 돌리지 않는다.** commit 결과를 모른다는 것은 commit이 이미 적용됐을
already have applied. Re-running the body would apply it a second time. Only the commit is retried, 수 있다는 뜻이다. 본문을 다시 돌리면 두 번 적용된다. commit만 재시도하고, 이미 commit된 transaction에
and a commit retry on an already-committed transaction is a no-op by design. 대한 commit 재시도는 설계상 아무 일도 하지 않는다.
- **A budget bounds both loops.** `MongoRetryBudget` limits attempts *and* elapsed time, with jittered - **예산이 두 loop를 모두 제한한다.** `MongoRetryBudget`은 시도 횟수 *와* 흐른 시간을 제한하고, 흔들림을
backoff (`delayBefore(attempt, random)`), so a struggling primary is not retried into the ground. 준 backoff(`delayBefore(attempt, random)`)를 쓴다. 힘든 primary를 재시도로 짓누르지 않는다.
`MongoRetryDecision` and `MongoRetryScope` (in `…api.error`) say what may be retried: `MongoRetryDecision`과 `MongoRetryScope`(`…api.error`에 있다)가 무엇을 재시도해도 되는지 말한다:
`MongoRetryScope.BODY`, `COMMIT_ONLY`, or `NONE`. `MongoRetryScope.BODY`, `COMMIT_ONLY`, `NONE`.
## 7. Ambiguous outcomes ## 7. 결과를 모르는 경우
`MongoExecutionOutcome` has six values, two of which are ambiguous and must not be collapsed: `MongoExecutionOutcome`의 값은 여섯이고, 그중 둘은 결과를 모르는 경우라 합치면 안 된다.
| Outcome | Did the write happen? | | 결과 | 쓰기가 일어났나? |
|---|---| |---|---|
| `NOT_SENT` | No. Safe to retry. | | `NOT_SENT` | 아니다. 재시도해도 안전하다. |
| `NO_WRITE_PERFORMED` | No — the server answered and did nothing. | | `NO_WRITE_PERFORMED` | 아니다. 서버가 답했고 아무것도 하지 않았다. |
| `WRITE_CONFIRMED` | Yes. | | `WRITE_CONFIRMED` | 그렇다. |
| `PARTIAL_BULK_WRITE` | Some of it. See `MongoBulkResult`. | | `PARTIAL_BULK_WRITE` | 일부만. `MongoBulkResult`를 본다. |
| `WRITE_RESULT_UNKNOWN` | **Unknown.** | | `WRITE_RESULT_UNKNOWN` | **모른다.** |
| `TRANSACTION_COMMIT_UNKNOWN` | **Unknown.** | | `TRANSACTION_COMMIT_UNKNOWN` | **모른다.** |
An unknown outcome is not a failure and must not be reported to a caller as one. The caller either 결과를 모르는 것은 실패가 아니고, 호출자에게 실패로 알리면 안 된다. 호출자는 맞춰 보거나
reconciles (`MongoCommitReconciler` re-reads a deterministic marker the body wrote) or surfaces the (`MongoCommitReconciler`가 본문이 쓴 결정적 표시를 다시 읽는다) 모른다는 사실을 그대로 위로 올린다.
ambiguity. See [runbooks/unknown-commit.md](runbooks/unknown-commit.md). [runbooks/unknown-commit.md](runbooks/unknown-commit.md)를 본다.
`MongoFailureContext` records only the design-permitted fields — outcome, category, operation name, `MongoFailureContext`는 설계가 허락한 필드만 남긴다: 결과, 분류, 연산 이름, collection profile, 재시도
collection profile, retry scope, attempt — never the query, the document, or the values. 범위, 시도 번호. query, 문서, 값은 남기지 않는다.
## 8. Failure translation ## 8. 실패 변환
`DefaultMongoFailureClassifier` classifies **labels before codes**. The server's error labels `DefaultMongoFailureClassifier`는 **코드보다 label을 먼저** 본다. 서버의 error label
(`TransientTransactionError`, `UnknownTransactionCommitResult`, `RetryableWriteError`) are the (`TransientTransactionError`, `UnknownTransactionCommitResult`, `RetryableWriteError`)이 재시도 가능 여부에
authoritative statement about retryability; an error code is a secondary signal whose meaning varies 대한 권위 있는 답이다. error code는 서버 버전마다 뜻이 바뀌는 보조 신호다.
by server version. `DefaultMongoFailureTranslator` maps a classification onto the stable exception `DefaultMongoFailureTranslator`가 분류를 안정된 예외 계층에 대응시킨다. 맞는 것이 없으면 driver 타입을
hierarchy, and anything unmatched becomes `MongoUnclassifiedFailureException` rather than leaking a 흘리지 않고 `MongoUnclassifiedFailureException`이 된다.
driver type.
## 9. Bulk writes ## 9. Bulk 쓰기
`MongoBulkExecutor` returns a `MongoBulkResult` with per-item `MongoBulkItemFailure` entries. An `MongoBulkExecutor`는 항목별 `MongoBulkItemFailure`를 담은 `MongoBulkResult`를 돌려준다. 순서 없는 bulk
unordered bulk write that partially fails is `PARTIAL_BULK_WRITE`, not a failure: some documents were 쓰기가 일부 실패하면 실패가 아니라 `PARTIAL_BULK_WRITE`다. 일부 문서는 쓰였다. 결과의 항목별 결과가
written. The result's per-item outcomes say which indexes succeeded and which failed, so a caller can 어느 index가 성공하고 어느 것이 실패했는지 말해 주므로, 호출자는 처음부터 다시 하지 않고 이어서 할 수 있다.
resume rather than replay.
`execute(context, documentType, plan)` maps every filter and update through the document type, as `execute(context, documentType, plan)`은 문서 하나 경로와 같이 모든 filter와 update를 document type에
the single-document path does, so `@Field` names and registered converters (`DomainDocumentId`, 맞춰 변환한다. 그래서 `@Field` 이름과 등록한 converter(`DomainDocumentId`, `BigInteger`)가 batch에서도
`BigInteger`) mean the same thing in a batch. The command's byte ceiling is measured on those mapped 같은 뜻이다. 명령의 바이트 상한은 무엇이든 보내기 전에 그렇게 변환한 문서로 잰다.
documents before anything is sent.
+6 -1
View File
@@ -84,7 +84,12 @@ leaf 목록과 허용 의존 방향의 원본은 `src/config/architecture/module
runtimeOnly project(':adapter:outbound:persistence-note') runtimeOnly project(':adapter:outbound:persistence-note')
``` ```
5. 확인: `./gradlew :adapter:outbound:persistence-note:check architectureCheck --console=plain`. 5. 확인: 새 leaf의 `check`와 `architectureCheck`를 돈다. 아래 Gradle 경로는 서비스가 만든 leaf의 것이라
이 템플릿에는 없다.
```bash
./gradlew :adapter:outbound:persistence-note:check architectureCheck --console=plain
```
## 3. 서비스 leaf가 등록해야 하는 bean ## 3. 서비스 leaf가 등록해야 하는 bean
+55 -56
View File
@@ -1,85 +1,84 @@
# Document Modeling Guide # 문서 모델링 가이드
Design §7–§9. The platform does not own your documents — D-01 is explicit that the domain owns 설계서 §7–§9. 플랫폼은 여러분의 문서를 소유하지 않는다. D-01이 분명히 말한다: `@Document`, repository,
`@Document`, repositories, queries, index requirements and schema version. What the platform owns is query, index 요구 사항, schema 버전은 도메인이 소유한다. 플랫폼이 소유하는 것은 collection에 운영
the set of modeling decisions that are expensive to reverse once a collection holds production data. 데이터가 쌓인 뒤에는 되돌리기 비싼 모델링 결정들이다.
## 1. There is no `CommonMongoRepository` ## 1. `CommonMongoRepository`는 없다
A generic `CommonMongoRepository<T, ID>` is listed under explicitly unsupported (§3.4), and the 범용 `CommonMongoRepository<T, ID>`는 명시적으로 지원하지 않는 목록(§3.4)에 있다. 이유는 순수성이 아니다.
reason is not purity. A shared supertype forces every collection to share an id strategy, a 공통 상위 타입은 모든 collection에 같은 id 전략, 같은 일관성 profile, 같은 query 면을 강요한다. 다른 것이
consistency profile and a query surface, and the first collection that needs a different one either 필요한 첫 collection은 cast를 하거나 새는 generic 인자를 얻는다. aggregate마다 Spring Data repository를
gets a cast or a leaky generic parameter. Declare a Spring Data repository per aggregate. 선언한다.
## 2. Embed or reference ## 2. 넣을까, 가리킬까
`MongoDocumentModelManifest` records the decision per collection so it is reviewable, and `MongoDocumentModelManifest`가 collection마다 이 결정을 적어 검토할 수 있게 하고,
`MongoDocumentModelValidator` refuses the combinations that do not survive growth. `MongoDocumentModelValidator`가 커지면 버티지 못하는 조합을 거부한다.
| Descriptor | Use when | | Descriptor | 쓰는 때 |
|---|---| |---|---|
| `EmbeddedCollectionDescriptor` | The child is read with the parent, is bounded, and has no independent lifecycle. Declare `maxElements`; an unbounded array is the single most common way a document reaches the size limit. | | `EmbeddedCollectionDescriptor` | 자식을 부모와 함께 읽고, 개수에 상한이 있고, 따로 사는 수명이 없다. `maxElements`를 선언한다. 상한 없는 배열이 문서가 크기 한도에 닿는 가장 흔한 길이다. |
| `MongoReferenceDescriptor` | The child is queried independently, is unbounded, or outlives the parent. Declare `MongoReferenceLifecycle` so the deletion story is written down rather than discovered. | | `MongoReferenceDescriptor` | 자식을 따로 조회하거나, 개수에 상한이 없거나, 부모보다 오래 산다. `MongoReferenceLifecycle`을 선언해서 삭제 방식을 나중에 발견하지 않고 미리 적어 둔다. |
The validator rejects an embedded collection without a bound, and a reference whose lifecycle says validator는 상한 없는 embedded collection을 거부한다. lifecycle이 「부모가 자식을 소유한다」고 하면서
the child is owned by the parent but which is also referenced from elsewhere. 다른 곳에서도 가리키는 reference도 거부한다.
## 3. Size budget ## 3. 크기 예산
`MongoDocumentSizeBudget`: `MongoDocumentSizeBudget`:
| Constant | Bytes | Meaning | | 상수 | 바이트 | 뜻 |
|---|---|---| |---|---|---|
| `MONGODB_HARD_LIMIT_BYTES` | 16 MiB | MongoDB's own limit. | | `MONGODB_HARD_LIMIT_BYTES` | 16 MiB | MongoDB 자체 한도. |
| `PLATFORM_CEILING_BYTES` | 4 MiB | The largest budget the platform will accept. | | `PLATFORM_CEILING_BYTES` | 4 MiB | 플랫폼이 받아들이는 가장 큰 예산. |
| `DEFAULT_BYTES` | 2 MiB | `MongoDocumentSizeBudget.standard()`. | | `DEFAULT_BYTES` | 2 MiB | `MongoDocumentSizeBudget.standard()`. |
A budget above the ceiling is refused at construction. Budgeting to 16 MiB means the failing write 상한을 넘는 예산은 생성할 때 거부한다. 예산을 16 MiB로 잡으면 실패한 쓰기가 첫 증상이고, 그때는 이미
is the first symptom, and by then the collection is already full of near-limit documents. collection이 한도 가까운 문서로 가득하다.
## 4. Identity ## 4. 식별자
`DomainDocumentId` is written to `_id` as a BSON string by `DomainIdWriteConverter`. Any other `DomainIdWriteConverter`가 `DomainDocumentId`를 `_id`에 BSON 문자열로 쓴다. 그 밖의 표현은 문서 클래스
representation is the document class's own field type. Pick the representation once per collection: 자신의 필드 타입이 정한다. collection마다 표현을 한 번 고른다.
- `OBJECT_ID` — server-generated, monotonic, 12 bytes. Good default when the domain has no natural id. - `OBJECT_ID` — 서버가 만들고, 단조 증가하며, 12바이트다. 도메인에 자연 id가 없을 때 좋은 기본값이다.
- `UUID_BINARY` — a domain UUID stored as `Binary` subtype 4 (`STANDARD`). Never store a UUID as a - `UUID_BINARY` — 도메인 UUID를 `Binary` subtype 4(`STANDARD`)로 저장한다. 「읽기 쉬워서」 UUID를
string "because it is easier to read"; it doubles the index size and loses the type. 문자열로 저장하지 않는다. index 크기가 두 배가 되고 타입을 잃는다.
- `STRING` — a natural key that is genuinely a string (a slug, an external system's id). - `STRING` — 정말 문자열인 자연 key(slug, 외부 시스템의 id).
An `_id` choice is effectively permanent: it is the shard key candidate, the resume-token join key `_id` 선택은 사실상 영구적이다. shard key 후보이고, resume token의 join key이고, 페이지 나누기의 동률
and the pagination tie-breaker. 처리 기준이다.
## 5. Schema version ## 5. Schema 버전
Every long-lived collection carries `DocumentSchemaVersion`. `MongoSchemaVersionPolicy` and 오래 사는 collection은 모두 `DocumentSchemaVersion`을 가진다. `MongoSchemaVersionPolicy`와
`MongoSchemaVersionRange` say which versions the running code can read; a document outside the range `MongoSchemaVersionRange`가 실행 중인 코드가 읽을 수 있는 버전을 말한다. 범위 밖의 문서는 필드가 빠진
raises `MongoDataSchemaUnsupportedException` rather than being silently mapped with missing fields. 채 조용히 매핑되지 않고 `MongoDataSchemaUnsupportedException`을 던진다.
Write the range down before the migration, not after: the range is what lets old and new instances 범위는 마이그레이션 뒤가 아니라 앞에 적는다. 범위가 있어야 rolling 배포 중에 옛 인스턴스와 새 인스턴스가
run at once during a rolling deploy. 함께 돈다.
## 6. Type metadata ## 6. 타입 metadata
`@LongLivedMongoDocument` marks a document whose stored type alias must not be a Java class name. `@LongLivedMongoDocument`는 저장하는 타입 별칭이 Java 클래스 이름이면 안 되는 문서를 표시한다.
`MongoTypeMetadataRegistry` maps alias → class. Storing the FQCN means moving or renaming the class `MongoTypeMetadataRegistry`가 별칭 → 클래스를 대응시킨다. FQCN을 저장하면 클래스를 옮기거나 이름을 바꾸는
becomes a data migration; storing an alias keeps it a refactor. See 일이 데이터 마이그레이션이 된다. 별칭을 저장하면 리팩터링으로 남는다.
[bson-mapping-guide.md](bson-mapping-guide.md) §4. [bson-mapping-guide.md](bson-mapping-guide.md) §5를 본다.
## 7. Collection profiles ## 7. Collection profile
`MongoCollectionProfileRegistry` binds a `CollectionProfileName` to its consistency profile, budget `MongoCollectionProfileRegistry`는 `CollectionProfileName`을 그 일관성 profile, 예산, 허용 목록에 묶는다.
and allowlist. A collection that is not registered cannot be reached through 등록하지 않은 collection에는 `MongoImperativeExecutor`로 닿을 수 없다. 허용 목록이 검토하지 않은
`MongoImperativeExecutor` — the allowlist is the mechanism that keeps an collection이 실수로 운영에 나타나는 것을 막는다.
unreviewed collection from appearing in production by accident.
## 8. What to write down before the first insert ## 8. 첫 insert 전에 적어 둘 것
1. Embed/reference decision per child collection, with bounds. 1. 자식 collection마다 넣을지/가리킬지와 그 상한.
2. Size budget. 2. 크기 예산.
3. `_id` representation. 3. `_id` 표현.
4. Schema version range. 4. Schema 버전 범위.
5. Index manifest (see [schema-index-migration-guide.md](schema-index-migration-guide.md)). 5. Index manifest([schema-index-migration-guide.md](schema-index-migration-guide.md)).
6. Consistency profile (see [consistency-transaction-guide.md](consistency-transaction-guide.md)). 6. 일관성 profile([consistency-transaction-guide.md](consistency-transaction-guide.md)).
Each of these is cheap now and a migration later. 모두 지금은 싸고, 나중에는 마이그레이션이다.
+68 -73
View File
@@ -1,110 +1,105 @@
# Query and Aggregation Guide # Query와 aggregation 가이드
Design §17–§19, decision D-11. Every query and every pipeline is a registered, bounded thing. Free-form 설계서 §17–§19, 결정 D-11. 모든 query와 모든 pipeline은 등록하고 상한을 둔 것이어야 한다. 자유 형식
JSON queries and unbounded pipelines are explicitly unsupported (§3.4). JSON query와 상한 없는 pipeline은 명시적으로 지원하지 않는다(§3.4).
## 1. Registered operations ## 1. 등록한 연산
Every execution carries a `MongoOperationContext`: a `MongoOperationName`, a `DatabaseProfileName`, a 모든 실행은 `MongoOperationContext`를 가진다: `MongoOperationName`, `DatabaseProfileName`,
`CollectionProfileName`, a `MongoOperationType` and a `MongoOperationScope`. `CollectionProfileName`, `MongoOperationType`, `MongoOperationScope`.
`MongoOperationName` matches `[a-z][a-z0-9.-]{2,95}`. It is the join key for the budget registry, the `MongoOperationName`은 `[a-z][a-z0-9.-]{2,95}`에 맞아야 한다. 이 이름이 예산 registry, 일관성 registry,
consistency registry, the metric tag and the log line — a free-form or interpolated name breaks all metric tag, 로그 줄을 잇는 key다. 자유 형식이나 값을 끼워 넣은 이름은 넷을 한꺼번에 깨뜨린다. 그래서
four at once, which is why the pattern is enforced at construction. 생성할 때 패턴을 강제한다.
`MongoOperationScope` uses an `UNSPECIFIED` sentinel rather than `null`, so "the caller did not say" `MongoOperationScope`는 `null` 대신 `UNSPECIFIED` 표시값을 쓴다. 「호출자가 말하지 않았다」가 아래에서
is a value the policy layer can reject rather than an NPE further down. 터지는 NPE가 아니라 정책 계층이 거부할 수 있는 값이 된다.
## 2. Query guardrails ## 2. Query 보호 장치
`PolicyAwareMongoQueryBuilder` builds a query from `MongoFieldDescriptor` + `MongoOperator` pairs `PolicyAwareMongoQueryBuilder`는 `MongoFieldDescriptor` + `MongoOperator` 쌍으로 `MongoQueryPolicy`에
against a `MongoQueryPolicy`. The policy refuses: 맞춰 query를 만든다. 정책이 거부하는 것:
- a field not in the collection's allowlist - collection 허용 목록에 없는 필드
- an operator not allowed for that field - 그 필드에 허용하지 않은 operator
- a sort on an unindexed field - index 없는 필드의 정렬
- `$where`, `$expr` with arbitrary JavaScript, and server-side evaluation generally - `$where`, 임의 JavaScript를 쓰는 `$expr`, 그리고 서버 쪽 평가 전반
- an unbounded `$regex` - 상한 없는 `$regex`
`MongoRegexPolicy` requires an anchored prefix pattern and bounds the pattern length. An unanchored `MongoRegexPolicy`는 앞을 고정한 prefix 패턴을 요구하고 패턴 길이에 상한을 둔다. 앞을 고정하지 않은
regex is a collection scan wearing an index's clothes, and a user-supplied one is a denial-of-service regex는 index를 쓰는 척하는 collection 전체 scan이고, 사용자가 넣은 regex는 서비스 거부 공격의 재료다.
primitive.
`MongoSortDescriptor` pairs a field with a direction and is validated against the index manifest, so `MongoSortDescriptor`는 필드와 방향을 짝짓고 index manifest와 대조한다. 디스크로 넘칠 정렬은 운영이 아니라
a sort that would spill to disk fails review rather than production. 검토에서 실패한다.
## 3. Operation budgets ## 3. 연산 예산
`MongoOperationBudget` bounds four things at once: `MongoOperationBudget`은 네 가지를 한꺼번에 제한한다.
| Bound | Why | | 상한 | 이유 |
|---|---| |---|---|
| `maxTimeMS` | The server stops working on a query nobody is waiting for. | | `maxTimeMS` | 아무도 기다리지 않는 query를 서버가 멈춘다. |
| result limit | An unbounded result set is an OOM with extra steps. | | 결과 개수 상한 | 상한 없는 결과는 단계가 몇 개 더 붙은 OOM이다. |
| batch size | Bounds the per-round-trip memory. | | batch 크기 | 왕복 한 번의 메모리를 제한한다. |
| examined-document ceiling | Catches an index regression that a time limit alone would hide on a fast day. | | 검사한 문서 수 상한 | 빠른 날에는 시간 상한만으로 숨겨지는 index 회귀를 잡는다. |
`MongoBudgetPolicyRegistry` binds a budget to an operation name; `MongoBudgetEnforcer` applies it and `MongoBudgetPolicyRegistry`가 예산을 연산 이름에 묶는다. `MongoBudgetEnforcer`가 그것을 적용한다. 요청이
raises `MongoOperationRejectedException` before execution when a request exceeds it, and 예산을 넘으면 실행 전에 `MongoOperationRejectedException`을 던지고, 서버가 상한을 집행하면
`MongoTimeoutException` when the server enforces it. `MongoTimeoutException`이 난다.
## 4. Keyset pagination ## 4. Keyset 페이지 나누기
Unbounded `skip` is unsupported: `skip(1_000_000)` makes the server walk a million documents to throw 상한 없는 `skip`은 지원하지 않는다. `skip(1_000_000)`은 서버가 버릴 문서 백만 개를 훑게 한다. 그래서
them away, so page 1000 costs a thousand times page 1. 1000쪽은 1쪽의 천 배가 든다.
`MongoKeysetQueryBuilder` builds the resume predicate lexicographically. For a sort on `(a DESC, _id `MongoKeysetQueryBuilder`는 이어 읽기 조건을 사전순으로 만든다. `(a DESC, _id DESC)` 정렬에서 `(A, I)`
DESC)` resuming after `(A, I)`: 다음부터 읽으면 이렇다.
``` ```
(a < A) OR (a = A AND _id < I) (a < A) OR (a = A AND _id < I)
``` ```
`validate()` rejects a `MongoKeysetSort` without a unique tie-breaker. Without one, two documents with `validate()`는 유일한 동률 처리 기준이 없는 `MongoKeysetSort`를 거부한다. 기준이 없으면 정렬 값이 같은 두
the same sort value straddle the page boundary and one of them is skipped or repeated — invisibly, 문서가 페이지 경계에 걸쳐 하나가 빠지거나 두 번 나온다. 눈에 띄지 않고, 동시 요청이 있을 때만 생긴다.
and only under concurrency.
`MongoNullSortOrdering` makes null placement explicit, because MongoDB's own ordering of missing `MongoNullSortOrdering`은 null의 위치를 명시한다. 필드 없음, null, 값 있음에 대한 MongoDB 자체 정렬 순서는
versus null versus present is not what most people assume. 대부분이 짐작하는 것과 다르다.
### Cursors are authenticated ### Cursor는 인증한다
`MongoKeysetCursorCodec` signs the cursor with HMAC-SHA256 and compares with `MongoKeysetCursorCodec`은 cursor에 HMAC-SHA256 서명을 하고 `MessageDigest.isEqual`(일정 시간 비교)로
`MessageDigest.isEqual` (constant time). An unsigned cursor is a client-controlled query predicate: a 비교한다. 서명 없는 cursor는 client가 조종하는 query 조건이다. 호출자가 그것을 고쳐 받은 적 없는 범위를
caller can edit it to read a range they were never offered. A tampered or truncated cursor yields 읽을 수 있다. 고치거나 잘린 cursor는 `MongoCursorException`이 되고, 반쯤 해석한 이어 읽기 위치가 되지
`MongoCursorException`, never a partially-decoded resume position. 않는다.
## 5. Aggregation guardrails ## 5. Aggregation 보호 장치
`MongoAggregationPlan` is a registered pipeline: an ordered list of `MongoAggregationStageDescriptor` `MongoAggregationPlan`은 등록한 pipeline이다. `MongoAggregationStageDescriptor`의 순서 있는 목록이고
validated against a `MongoAggregationProfile`. `PolicyAwareMongoAggregationExecutor` runs only a `MongoAggregationProfile`과 대조한다. `PolicyAwareMongoAggregationExecutor`는 등록한 plan만 돌린다.
registered plan.
`MongoAggregationRisk` grades each stage, and the profile sets the ceiling: `MongoAggregationRisk`가 stage마다 위험 등급을 매기고, profile이 허용 상한을 정한다.
| Risk | Stages | Policy | | 위험 | Stage | 정책 |
|---|---|---| |---|---|---|
| low | `$match` on an indexed prefix, `$limit`, `$project` | Always allowed. | | low | index 앞부분에 대한 `$match`, `$limit`, `$project` | 늘 허용한다. |
| moderate | `$group`, `$sort` with an index, `$unwind` with a bound | Allowed within budget. | | moderate | `$group`, index 있는 `$sort`, 상한 있는 `$unwind` | 예산 안에서 허용한다. |
| high | `$lookup`, `$graphLookup`, `$facet`, unindexed `$sort` | Requires explicit approval in the profile. | | high | `$lookup`, `$graphLookup`, `$facet`, index 없는 `$sort` | profile의 명시적 승인이 필요하다. |
| forbidden | `$out`, `$merge` outside the admin plane, `$function`, `$accumulator` | Refused. | | forbidden | admin plane 밖의 `$out`·`$merge`, `$function`, `$accumulator` | 거부한다. |
`allowDiskUse` is a declared property of the plan, not a runtime flag. A pipeline that needs disk is a `allowDiskUse`는 실행 중 flag가 아니라 plan에 선언하는 속성이다. 디스크가 필요한 pipeline은 모양을 검토해야
pipeline whose shape should be reviewed. 하는 pipeline이다.
## 6. Geospatial ## 6. 지리 공간
`MongoGeoQuery` + `MongoGeoPoint` + `MongoGeoDistance` over a `2dsphere` index. Distances are metres `MongoGeoQuery` + `MongoGeoPoint` + `MongoGeoDistance`를 `2dsphere` index 위에서 쓴다. 거리는 구 위의
on a sphere (`nearSphere` with `maxDistance`), never degrees — a degree of longitude is a different 미터다(`nearSphere`와 `maxDistance`). 도(degree)는 쓰지 않는다. 경도 1도는 오슬로와 나이로비에서 거리가
distance in Oslo than in Nairobi, and a radius expressed in degrees is a bug that only shows up away 다르다. 도로 적은 반경은 적도에서 멀어져야 드러나는 결함이다. `SpringMongoGeospatialOperations`가 Spring
from the equator. `SpringMongoGeospatialOperations` is the Spring Data binding; Data 연결이고, `MongoGeospatialOperations`가 port다.
`MongoGeospatialOperations` is the port.
## 7. Native capability gateway ## 7. Native capability gateway
When a registered operation genuinely needs something outside the Stable API, it goes through 등록한 연산에 정말 Stable API 밖의 것이 필요하면 driver를 바로 쓰지 않고
`MongoNativeCapabilityGateway` (`PolicyAwareMongoNativeGateway`), never through the driver directly. `MongoNativeCapabilityGateway`(`PolicyAwareMongoNativeGateway`)를 거친다. 허가 순서는 고정이다.
The admission order is fixed:
``` ```
capability registered capability registered
@@ -121,6 +116,6 @@ capability registered
→ execute → execute
``` ```
`ApprovedMongoNativeOperation` is the registration record; `MongoNativeOperationPolicy` is the policy. `ApprovedMongoNativeOperation`이 등록 기록이고 `MongoNativeOperationPolicy`가 정책이다. admin plane 명령이
An admin-plane command reaching this gateway is refused regardless of capability — the admin plane has 이 gateway에 오면 capability와 상관없이 거부한다. admin plane은 자기 credential과 자기 client를 쓴다
its own credential and its own client (see [security-observability.md](security-observability.md)). ([security-observability.md](security-observability.md)).
+87 -87
View File
@@ -1,43 +1,46 @@
# MongoDB Document Persistence Platform — Repository Adaptation Contract # MongoDB 문서 영속성 플랫폼 — 저장소 적응 계약
**Design source:** `docs/design/2026-08-11-mongodb-document-persistence-platform-design.md` **설계서:** `docs/design/2026-08-11-mongodb-document-persistence-platform-design.md`
**Stable plan:** `docs/history/plans/2026-08-11-mongodb-document-persistence-platform-implementation-plan.md` **Stable 계획서:** `docs/history/plans/2026-08-11-mongodb-document-persistence-platform-implementation-plan.md`
**Advanced plan:** `docs/history/plans/2026-08-11-mongodb-advanced-capabilities-expansion-plan.md` **Advanced 계획서:** `docs/history/plans/2026-08-11-mongodb-advanced-capabilities-expansion-plan.md`
The design package declares its own module root (`modules/mongodb`) and root package 설계 패키지는 자기 모듈 root(`modules/mongodb`)와 root package(`io.backend.skeleton.mongodb`)를 계약이
(`io.backend.skeleton.mongodb`) as *implementation assumptions*, not as contract. This file is the 아니라 *구현 가정*으로 적었다. 이 파일은 그 가정한 배치를 이 저장소에 어떻게 옮겼는지 적은 유일한
single record of how that assumed layout was mapped onto this repository. Only paths, build DSL, 기록이다. 바뀐 것은 경로, 빌드 DSL, 조립 루트의 소유뿐이다. 공개 계약, 정책 순서, 오류 의미는 명세대로
and composition-root ownership changed. Public contracts, policy order, and error semantics are 구현했다.
implemented exactly as specified.
## 1. Why the module layout differs ## 1. 모듈 배치가 다른 이유
The design assumes 19 Stable Gradle projects under `modules/mongodb/` and 12 Advanced projects 설계는 `modules/mongodb/` 아래에 Stable Gradle 프로젝트 19개, `modules/mongodb-advanced/` 아래에 Advanced
under `modules/mongodb-advanced/`. This repository is a Clean Architecture template whose 프로젝트 12개를 가정한다. 이 저장소는 Clean Architecture 템플릿이고, **닫힌 쪽으로 실패하는 registry**
**fail-closed registry** (`src/config/architecture/modules.json`, enforced by `src/settings.gradle` (`src/config/architecture/modules.json`)가 Gradle 프로젝트 목록을 정한다. `src/settings.gradle`이
and `verifyCleanArchitectureDependencies`) declares **exactly 19 leaf identities**. Creating 31 more registry에 있는 프로젝트만 포함하고, `verifyCleanArchitectureDependencies`가 허용하지 않은 의존을 막는다.
Gradle projects would violate HARD-STOP #5 in `AGENTS.md`. 설계의 모듈마다 Gradle 프로젝트를 만들면 `AGENTS.md`의 HARD-STOP 5번(registry·Gradle 의존성 검증 위반)에
걸린다.
Therefore the design's 31 modules become **package boundaries inside the registered leaf** 그래서 설계의 모듈 31개는 등록된 leaf `:adapter:outbound:persistence-mongo` **안의 package 경계**가
`:adapter:outbound:persistence-mongo`, following the precedent already set by 된다. [docs/httpclient/repository-adaptation.md](../httpclient/repository-adaptation.md)가 먼저 세운
[docs/httpclient/repository-adaptation.md](../httpclient/repository-adaptation.md). The design's 방식을 따른다. 설계의 모듈 의존 표(§6.3)는 `MongoModuleBoundaryTest`가 **닫힌 edge 행렬**로 강제한다.
module dependency table (§6.3) is enforced by `MongoModuleBoundaryTest` as a **closed edge matrix**:
every top-level package is declared with the packages it may import, the matrix is compared against
the tree for exact equality, and every observed edge must appear in it. A forbidden edge fails the
build the same way a missing Gradle dependency would, and so does a new package nobody registered.
This used to be a stronger claim than the test. The rules forbade a handful of reverse dependencies - 최상위 package마다 import해도 되는 package를 선언한다.
and said nothing about the rest, so edges outside the design's DAG existed and passed, among them - 행렬과 실제 트리가 정확히 같은지 비교한다.
`geo → imperative`. They are declared in the matrix now rather than removed — each is a real coupling the code relies on, and - 관측한 edge는 모두 행렬에 있어야 한다.
the point of recording them is that the next one is a decision instead of an accident.
## 2. Package mapping 금지된 edge는 Gradle 의존이 빠졌을 때와 똑같이 빌드를 실패시킨다. 아무도 등록하지 않은 새 package도
그렇다.
예전에는 이 문서의 주장이 테스트보다 강했다. 규칙은 역방향 의존 몇 개만 막고 나머지는 말하지 않았다.
그래서 설계의 DAG 밖의 edge가 있었고 통과했다. `geo → imperative`가 그중 하나다. 지금은 그런 edge를
지우지 않고 행렬에 선언했다. 하나하나가 코드가 실제로 기대는 결합이다. 적어 두는 이유는 다음 edge가
사고가 아니라 결정이 되게 하려는 것이다.
## 2. Package 대응
Root package: `io.backend.skeleton.mongodb` → `dev.caskeleton.adapter.outbound.mongo`. Root package: `io.backend.skeleton.mongodb` → `dev.caskeleton.adapter.outbound.mongo`.
### 2.1 Stable modules ### 2.1 Stable 모듈
| Design module | Repository package | | 설계 모듈 | 저장소 package |
|---|---| |---|---|
| `mongodb-core-api` | `…outbound.mongo.api` (+ `.capability`, `.consistency`, `.error`, `.mapping`, `.observation`, `.profile`, `.schema`) | | `mongodb-core-api` | `…outbound.mongo.api` (+ `.capability`, `.consistency`, `.error`, `.mapping`, `.observation`, `.profile`, `.schema`) |
| `mongodb-spring-data` | `…outbound.mongo.mapping` (+ `.type`), `…outbound.mongo.failure` | | `mongodb-spring-data` | `…outbound.mongo.mapping` (+ `.type`), `…outbound.mongo.failure` |
@@ -52,79 +55,76 @@ Root package: `io.backend.skeleton.mongodb` → `dev.caskeleton.adapter.outbound
| `mongodb-observability` | `…outbound.mongo.observation` | | `mongodb-observability` | `…outbound.mongo.observation` |
| `mongodb-security` | `…outbound.mongo.security` (+ `.admin`), `…outbound.mongo.nativecap` | | `mongodb-security` | `…outbound.mongo.security` (+ `.admin`), `…outbound.mongo.nativecap` |
| `mongodb-spring-boot-starter` | `…outbound.mongo.autoconfigure` | | `mongodb-spring-boot-starter` | `…outbound.mongo.autoconfigure` |
| `mongodb-testkit-core` | `…outbound.mongo.testkit.mapping`, `.compat`, `.performance` (`testkit` source set) | | `mongodb-testkit-core` | `…outbound.mongo.testkit.mapping`, `.compat`, `.performance` (`testFixtures` source set) |
| `mongodb-testkit-replicaset` | `…outbound.mongo.testkit.rs` (`testkit` source set) | | `mongodb-testkit-replicaset` | `…outbound.mongo.testkit.rs` (`testFixtures`, 컨테이너 fixture는 `mongoProviderTestkit` source set) |
| `mongodb-testkit-failover` | `…outbound.mongo.testkit.failover` (`testkit` source set) | | `mongodb-testkit-failover` | `…outbound.mongo.testkit.failover` (`testFixtures`, 컨테이너 fixture는 `mongoProviderTestkit` source set) |
| `mongodb-testkit-migration` | `…outbound.mongo.testkit.migration` (`testkit` source set) | | `mongodb-testkit-migration` | `…outbound.mongo.testkit.migration` (`testFixtures` source set) |
`…outbound.mongo.architecture` has no design counterpart: it holds the `@MongoOperation` marker and `…outbound.mongo.architecture`는 설계에 짝이 없다. `testFixtures` source set에 있고, `@MongoOperation`
the reusable ArchUnit rule set a fork applies to its own document/repository code. 표시 annotation과, 파생 서비스가 자기 document·repository 코드에 적용하는 재사용 ArchUnit 규칙 묶음
(`MongoRepositoryArchitectureRules`)을 가진다.
### 2.2 Advanced modules ### 2.2 Advanced 모듈
| Design module | Repository package | | 설계 모듈 | 저장소 package |
|---|---| |---|---|
| `mongodb-sharding` | `…outbound.mongo.advanced.sharding` (+ `.admin` for the D4 shard plane) | | `mongodb-sharding` | `…outbound.mongo.advanced.sharding` (+ D4 shard plane용 `.admin`) |
| `mongodb-csfle` | `…outbound.mongo.advanced.encryption.csfle` | | `mongodb-csfle` | `…outbound.mongo.advanced.encryption.csfle` |
| `mongodb-queryable-encryption` | `…outbound.mongo.advanced.encryption.qe` | | `mongodb-queryable-encryption` | `…outbound.mongo.advanced.encryption.qe` |
| `mongodb-tenancy-shared` | `…outbound.mongo.advanced.tenancy.shared` | | `mongodb-tenancy-shared` | `…outbound.mongo.advanced.tenancy.shared` |
| `mongodb-tenancy-database` | `…outbound.mongo.advanced.tenancy.database` | | `mongodb-tenancy-database` | `…outbound.mongo.advanced.tenancy.database` |
| `mongodb-testkit-sharded` | `…outbound.mongo.testkit.sharded` (`testkit` source set) | | `mongodb-testkit-sharded` | `…outbound.mongo.testkit.sharded` (`testFixtures` source set) |
`mongodb-timeseries`, `mongodb-search`, `mongodb-vector-search`, `mongodb-gridfs-compat` and `mongodb-timeseries`, `mongodb-search`, `mongodb-vector-search`, `mongodb-gridfs-compat`,
`mongodb-testkit-atlas` have no package any more: each was an operations interface with no `mongodb-testkit-atlas`는 이제 package가 없다. 각각 구현 없는 operations interface와 그것을 매개변수로
implementation plus the descriptors that parametrised it, and was removed on 2026-09-25 채우던 descriptor뿐이었고, 2026-09-25에 지웠다(`docs/capability-status.md`).
(`docs/capability-status.md`).
The design's rule that a Stable module never depends on an Advanced one survives as an ArchUnit rule 설계의 「Stable 모듈은 Advanced 모듈에 의존하지 않는다」 규칙은 ArchUnit 테스트로 남았다
(`stableNeverDependsOnAdvanced`). Every Advanced entry point takes a `MongoAdvancedCapabilityGuard` (`MongoModuleBoundaryTest`의 `noStablePackageDependsOnAnAdvancedCapability`). 모든 Advanced 진입점은
and refuses construction unless its `MongoAdvancedCapabilityFlags` enable the matching capability. `MongoAdvancedCapabilityGuard`를 받고, 그 `MongoAdvancedCapabilityFlags`가 해당 capability를 켜지 않았으면
There is no configuration property behind the flags: the Advanced types are library API, and the 생성을 거부한다. flag 뒤에 설정 속성은 없다. Advanced 타입은 라이브러리 API이고, 그것을 만드는 도입 측
adopter's adapter that constructs them builds the guard. 어댑터가 guard를 만든다.
## 3. Other deliberate substitutions ## 3. 그 밖에 일부러 바꾼 것
| Design assumption | Repository reality | Adaptation | | 설계 가정 | 저장소 현실 | 적응 |
|---|---|---| |---|---|---|
| Gradle Kotlin DSL under `modules/mongodb*` | Groovy DSL, root `build.gradle` conventions, `LockMode.STRICT` locking | Dependencies declared in `src/adapter/outbound/persistence-mongo/build.gradle`; `gradle.lockfile` regenerated. | | `modules/mongodb*` 아래 Gradle Kotlin DSL | Groovy DSL, root `build.gradle` convention, `LockMode.STRICT` 잠금 | 의존성은 `src/adapter/outbound/persistence-mongo/build.gradle`에 선언하고 `gradle.lockfile`을 다시 만들었다. |
| `mongodb-spring-boot-starter` is a separate module the app depends on | `modules.json` gives `adapter-outbound-persistence-mongo` an explicit project boundary; runtime membership is derived from resolved runtime classpaths rather than a per-leaf registry field | The `autoconfigure` package stays inside the leaf and registers through the leaf's own `META-INF/spring/…AutoConfiguration.imports`. This differs from the httpclient precedent; dependency and runtime-membership gates decide whether the leaf is actually composed. | | `mongodb-spring-boot-starter`는 앱이 의존하는 별도 모듈 | `modules.json`이 `adapter-outbound-persistence-mongo`에 명시적 프로젝트 경계를 준다. 런타임 편입은 leaf별 registry 필드가 아니라 해석한 런타임 classpath에서 정해진다 | `autoconfigure` package는 leaf 안에 두고 leaf 자신의 `META-INF/spring/…AutoConfiguration.imports`로 등록한다. httpclient 선례와 다르다. leaf를 실제로 조립하는지는 의존성 게이트와 런타임 편입 게이트가 정한다. |
| Spring Boot 4.1 / Spring Data MongoDB 5.1 baseline | Repository baseline is Spring Boot 4.0.8 / Spring Data MongoDB 5.0.x | The platform targets the Spring Data MongoDB **API surface** common to both; no 5.1-only type is referenced. The support matrix records the actual pinned versions. | | Spring Boot 4.1 / Spring Data MongoDB 5.1 기준 | 저장소 기준은 Spring Boot 4.0 계열 / Spring Data MongoDB 5.0 계열이다. 정확한 버전은 `src/gradle/libs.versions.toml`의 `springBoot`와 leaf의 `gradle.lockfile`이다 | 플랫폼은 둘에 공통인 Spring Data MongoDB **API 면**만 쓴다. 5.1에만 있는 타입은 참조하지 않는다. 실제 고정 버전은 support matrix가 가리킨다. |
| `MongoRetryScope` lives in `mongodb-transaction` | The `mongodb-spring-data` failure translator must classify retry scope, and it cannot depend on `mongodb-transaction` | `MongoRetryScope` lives in `…api.error` (core-api), which both packages already depend on. Same values, same meaning, one legal position in the DAG. | | `MongoRetryScope`는 `mongodb-transaction`에 있다 | `mongodb-spring-data`의 실패 변환기가 재시도 범위를 분류해야 하는데 `mongodb-transaction`에 의존할 수 없다 | `MongoRetryScope`는 두 package가 이미 의존하는 `…api.error`(core-api)에 둔다. 값도 뜻도 같고, DAG에서 놓일 수 있는 자리는 하나다. |
| `mongodb-migration-flamingock` depends on Flamingock | Adding an unvetted external dependency is out of scope for this task, and the design itself requires the public contract not to depend on Flamingock types | The adapter is provider-neutral: it consumes a platform-owned `FlamingockChangeUnitView`. Wiring an actual Flamingock distribution is a one-file change behind that view. | | `mongodb-migration-flamingock`은 Flamingock에 의존한다 | 검증하지 않은 외부 의존성을 더하는 것은 이 작업 범위 밖이었다. 설계도 공개 계약이 Flamingock 타입에 의존하지 않기를 요구한다 | 어댑터는 provider 중립이다. 플랫폼이 소유한 `FlamingockChangeUnitView`를 받는다. 실제 Flamingock 배포판을 잇는 일은 그 view 뒤의 파일 하나만 바꾸면 된다. |
| Testkit as its own Gradle module | The design forbids production modules depending on the testkit | A dedicated `testkit` source set whose output is on the test compile/runtime classpaths only. ArchUnit rule `productionNeverDependsOnTestkit` enforces the direction. | | Testkit은 따로 된 Gradle 모듈 | 설계는 production 모듈이 testkit에 의존하는 것을 금한다 | testkit은 `testFixtures` source set(ADR-BUILD-001)에 둔다. 컨테이너가 필요한 provider fixture는 별도 `mongoProviderTestkit` source set에 두어 보통 단위 테스트가 Testcontainers를 얻지 않게 한다. 방향은 `MongoModuleBoundaryTest`의 `noProductionPackageDependsOnTheTestkit`이 강제한다. |
| Per-task `git commit` | `AGENTS.md`: commit policy is `human-only` | Implementation is delivered unstaged; commits are the human's action. This is the only plan step intentionally not executed, and it is recorded here. | | 작업마다 `git commit` | `AGENTS.md`: 커밋 정책은 `human-only` | 구현은 stage하지 않은 채 넘겼고, 커밋은 사람이 했다. 계획 중 일부러 실행하지 않은 단계는 이것 하나이고, 여기 적어 둔다. |
| `docs/mongodb/**`, `scripts/verify-mongodb-*.sh` | Repository already owns `docs/` and `scripts/` | Created at the same repository-relative paths. The two gate scripts were later removed (2026-08-15); see §5. | | `docs/mongodb/**`, `scripts/verify-mongodb-*.sh` | 저장소가 이미 `docs/`와 `scripts/`를 가진다 | 같은 저장소 상대 경로에 만들었다. 게이트 스크립트 둘은 지금도 있다(5절). |
## 4. What is unchanged from the design ## 4. 설계에서 바뀌지 않은 것
- D1 / D2 / D3 / D4 exposure planes and the ordered D3 admission sequence (§5). - D1 / D2 / D3 / D4 노출 plane과 순서가 정해진 D3 허가 절차(§5).
- Stable API V1 with `apiStrict=true` on the D1/D2 client generation; D3/D4 on separate generations. - D1/D2 client 세대에는 `apiStrict=true`인 Stable API V1. D3/D4는 별도 세대.
- `MongoExecutionOutcome`, including both ambiguous outcomes (`WRITE_RESULT_UNKNOWN`, - 결과를 모르는 두 경우(`WRITE_RESULT_UNKNOWN`, `TRANSACTION_COMMIT_UNKNOWN`)를 포함한
`TRANSACTION_COMMIT_UNKNOWN`), and `MongoFailureContext`'s permitted-field list. `MongoExecutionOutcome`, 그리고 `MongoFailureContext`가 허락하는 필드 목록.
- The complete stable exception hierarchy and the label-before-code classification order. - 안정된 예외 계층 전체와, 코드보다 label을 먼저 보는 분류 순서.
- The BSON representation manifest (UUID `STANDARD`, `Decimal128`, UTC instants, alias type metadata) - BSON 표현 manifest(UUID `STANDARD`, `Decimal128`, UTC 순간, 별칭 타입 metadata)와 문서 크기 예산.
and the document-size budget. - update operator를 먼저 쓰는 쓰기, 그리고 문서 전체 교체의 선행 조건인 낙관적 revision.
- Update-operator-first writes, and optimistic revision as the precondition for whole-document - 별개 loop인 transaction 본문 재시도와 commit 재시도: 본문 시도마다 새 session, commit 결과를 모르면
replacement. commit만 재시도. commit 결과를 모르면 본문을 다시 돌리지 않는다.
- Transaction body retry and commit retry as separate loops: a new session per body attempt, and - query, aggregation, index의 등록된 연산 이름과 manifest. 자유 형식 JSON query와 상한 없는 pipeline은
commit-only retry on unknown commit. The body is never replayed after a commit ambiguity. 없다.
- Registered operation names and manifests for query, aggregation and index; no free-form JSON query - 인증한 cursor와 유일한 동률 처리 기준을 요구하는 keyset 페이지 나누기.
and no unbounded pipeline. - TTL은 물리적 정리일 뿐이다. 접근 거부나 업무 일정의 유일한 근거가 아니다.
- Keyset pagination with an authenticated cursor and a unique tie-breaker requirement. - manifest가 소유한 index/validator 상태와, 소유하지 않은 것은 절대 지우지 않는 적용 정책.
- TTL as physical cleanup only, never the sole basis for access denial or business scheduling. - 가짓수가 적은 관측 tag, 명령 가리기, credential 참조 간접화.
- Manifest-owned index/validator state with an apply policy that never drops what it does not own. - Stable 릴리스 게이트의 증거 분류. Advanced 승격 요건(실제 토폴로지 증거)은 ADR-MONGO-ADV-001의 검토
- Low-cardinality observation tags, command redaction, and the credential reference indirection. 의무다. 그것을 검사하는 클래스는 없다. `scripts/verify-mongodb-advanced.sh`는 빠진 증거를 보고할 뿐이다.
- The Stable release gate's evidence categories. The Advanced promotion requirements
(actual-topology evidence) are a review obligation in ADR-MONGO-ADV-001; no class checks them.
## 5. Verification ## 5. 검증
The release-gate scripts `scripts/verify-mongodb-platform.sh` and 릴리스 게이트 스크립트 `scripts/verify-mongodb-platform.sh`와 `scripts/verify-mongodb-advanced.sh`가 있다.
`scripts/verify-mongodb-advanced.sh` are present and wrap the named Gradle lanes with no-skip evidence 이름을 지정한 Gradle lane을 돌리고, 건너뛴 lane을 통과로 세지 않으며, 승격 정보를 보고한다. 릴리스·승격
and promotion metadata. Use them when producing release/promotion evidence; the focused commands 증거를 만들 때 쓴다. 아래 명령은 로컬 진단에 계속 쓸모가 있다.
below remain useful for local diagnosis.
From `src/`: `src/`에서:
```bash ```bash
./gradlew :adapter:outbound:persistence-mongo:check --console=plain ./gradlew :adapter:outbound:persistence-mongo:check --console=plain
@@ -132,6 +132,6 @@ From `src/`:
./gradlew :app-bootstrap:architectureTest --console=plain ./gradlew :app-bootstrap:architectureTest --console=plain
``` ```
The container-backed lanes the gate ran behind `MONGODB_DOCKER=1` — `mongoCompatibilityTest`, 컨테이너가 필요한 lane(`mongoCompatibilityTest`, `mongoMigrationTest`, `mongoSecurityIntegrationTest`,
`mongoMigrationTest`, `mongoSecurityIntegrationTest`, `mongoReplicaSetTest`, `mongoFailoverTest`, `mongoReplicaSetTest`, `mongoFailoverTest`, `mongoPerformanceTest`)은 `check`에 들어 있지 않다.
`mongoPerformanceTest` — are now invoked by name or not at all. `MONGODB_DOCKER=1 bash scripts/verify-mongodb-platform.sh`로 돌리거나, 이름으로 하나씩 돌린다.
+60 -66
View File
@@ -1,98 +1,92 @@
--- ---
title: Runbook — MongoDB primary failover title: Runbook — MongoDB primary 장애 조치(failover)
category: mongodb category: mongodb
severity: P2 severity: P2
owner: oncall owner: oncall
last_updated: 2026-08-13 last_updated: 2026-08-13
status: active status: 운영
--- ---
# Runbook: MongoDB primary failover # Runbook: MongoDB primary 장애 조치(failover)
Design §29, scenarios `PRIMARY_KILL`, `NETWORK_PARTITION`, `SERVER_SELECTION_TIMEOUT`, 설계서 §29, 시나리오 `PRIMARY_KILL`, `NETWORK_PARTITION`, `SERVER_SELECTION_TIMEOUT`,
`WRITE_RESPONSE_LOSS`. `WRITE_RESPONSE_LOSS`.
## Symptoms ## 증상
- `MongoServerSelectionException` / `MongoConnectionException` spike, then recovery within seconds. - `MongoServerSelectionException` / `MongoConnectionException`이 치솟았다가 몇 초 안에 회복한다.
- `MongoSdamObservationListener` reports a topology change (primary removed, new primary elected). - `MongoSdamObservationListener`가 토폴로지 변화를 보고한다(primary 빠짐, 새 primary 선출).
- `MongoPoolObservationListener` shows checkout wait times rising while server-side command duration - `MongoPoolObservationListener`에서 connection checkout 대기 시간은 오르는데 서버 쪽 명령 시간은 평평하다.
stays flat — the wait is topology, not query cost. 기다린 원인은 query 비용이 아니라 토폴로지다.
- Latency spike on writes with no corresponding rise in read latency. - 쓰기 지연이 치솟는데 읽기 지연은 그만큼 오르지 않는다.
A failover that resolves in under ~15 s and produces no `WRITE_RESULT_UNKNOWN` is normal replica-set 약 15초 안에 끝나고 `WRITE_RESULT_UNKNOWN`을 만들지 않은 failover는 정상적인 replica set 동작이다.
behaviour and needs no action beyond confirming it self-healed. 스스로 회복했는지 확인하는 것 말고는 할 일이 없다.
## Diagnosis ## 진단
1. Confirm an election actually happened. SDAM events distinguish an election from "the database got 1. 선출이 실제로 있었는지 확인한다. SDAM 이벤트가 있어야 선출과 「DB가 느려졌다」를 구분한다. 없으면
slow"; without them the two are indistinguishable in application metrics. 애플리케이션 metric으로는 둘을 구분할 수 없다.
2. Split the failure categories. Metric tag `failureCategory`: 2. 실패 분류를 나눈다. Metric tag `failureCategory`:
- `SERVER_SELECTION` / `CONNECTION` → the driver could not reach a primary. `NOT_SENT`; safe. - `SERVER_SELECTION` / `CONNECTION` → driver가 primary에 닿지 못했다. `NOT_SENT`이고 안전하다.
- `TIMEOUT` with outcome `WRITE_RESULT_UNKNOWN` → a write may have applied. Not safe; see below. - 결과가 `WRITE_RESULT_UNKNOWN`인 `TIMEOUT` → 쓰기가 적용됐을 수 있다. 안전하지 않다. 아래를 본다.
- `TRANSACTION_COMMIT_UNKNOWN` → go to [unknown-commit.md](unknown-commit.md) instead. - `TRANSACTION_COMMIT_UNKNOWN` → 대신 [unknown-commit.md](unknown-commit.md)로 간다.
3. Check the election duration against `MongoRetryBudget`. If the election outlasted the budget, the 3. 선출에 걸린 시간을 `MongoRetryBudget`과 비교한다. 선출이 예산보다 길었으면 primary가 생기기 전에
retries were exhausted before a primary existed and callers saw errors that a longer budget would 재시도를 다 써 버렸고, 예산이 더 길었으면 흡수했을 오류를 호출자가 봤다.
have absorbed. 4. 새 primary가 기대한 region/AZ에 있는지 본다. 먼 노드로 failover하면 쓰기 지연이 잠깐이 아니라 계속
4. Check whether the new primary is in the expected region/AZ. A failover to a distant node changes 바뀐다.
write latency permanently, not transiently.
## Action ## 조치
**Self-healed (the common case).** **스스로 회복했다(흔한 경우).**
Confirm outcome distribution contains no `WRITE_RESULT_UNKNOWN`, record the election in the incident 결과 분포에 `WRITE_RESULT_UNKNOWN`이 없는지 확인하고, 선출을 장애 기록에 남기고 닫는다. 다시 돌릴 것은 없다.
log, and close. Nothing to replay.
**Writes with `WRITE_RESULT_UNKNOWN`.** **`WRITE_RESULT_UNKNOWN`인 쓰기가 있다.**
These writes may or may not have applied. Do not blind-retry. 이 쓰기는 적용됐을 수도, 아닐 수도 있다. 확인 없이 재시도하지 않는다.
- Idempotent operation (registered `MongoUpdateOperator` with an `AtomicFilter` precondition): retry. - 멱등 연산(`AtomicFilter` 선행 조건이 붙은 등록된 `MongoUpdateOperator`): 재시도한다. 선행 조건 덕분에
The precondition makes the second application a no-op. 두 번째 적용은 아무 일도 하지 않는다.
- Non-idempotent operation: reconcile by reading the target document and comparing against the - 멱등이 아닌 연산: 대상 문서를 읽어 의도한 결과 상태와 비교해 맞춰 본다. 쓰기가 반영되지 않았을 때만
intended post-state. Retry only if it does not reflect the write. 재시도한다.
**Server selection never recovers.** **server selection이 끝내 회복하지 않는다.**
The set has lost quorum — two of three nodes are down or partitioned. No client-side action fixes set이 quorum을 잃었다. 노드 셋 중 둘이 죽었거나 끊겼다. client 쪽에서 고칠 방법은 없다. 과반을 되살리도록
this; escalate to the database owner to restore a majority. The application should be failing closed, DB 소유자에게 올린다. 애플리케이션은 큐에 쌓지 않고 닫힌 쪽으로 실패하고 있어야 한다.
not queueing.
**Elections are frequent (more than one a day, unprompted).** **선출이 잦다(이유 없이 하루 한 번 넘게).**
This is an infrastructure symptom, not an application one: check node resource saturation, disk 애플리케이션이 아니라 인프라 증상이다. 노드 자원 포화, primary의 디스크 지연, member 사이 네트워크 안정성을
latency on the primary, and network stability between members. Repeated elections cause repeated 본다. 선출이 반복되면 결과를 모르는 구간도 반복된다.
unknown-outcome windows.
## Escalation ## 상향 보고
- P2 → P1 if server selection has failed for more than 2 minutes, or if any non-idempotent write - server selection이 2분 넘게 실패했거나, 멱등이 아닌 쓰기가 `WRITE_RESULT_UNKNOWN`을 돌려받고 맞춰 볼 수
returned `WRITE_RESULT_UNKNOWN` and cannot be reconciled. 없으면 P2 → P1.
- Page the database owner for quorum loss, and the service owner for reconciliation of ambiguous - quorum 손실은 DB 소유자를, 결과를 모르는 쓰기를 맞춰 보는 일은 서비스 소유자를 호출한다.
writes.
## Verification ## 확인
The failover lane reproduces this deliberately: failover lane이 이 상황을 일부러 재현한다.
```bash ```bash
cd src cd src
./gradlew :adapter:outbound:persistence-mongo:mongoFailoverTest --console=plain ./gradlew :adapter:outbound:persistence-mongo:mongoFailoverTest --console=plain
``` ```
It starts a real three-node set (`MongoThreeNodeReplicaSet`), stops the primary 이 lane은 실제 노드 세 개짜리 set(`MongoThreeNodeReplicaSet`)을 띄우고, primary를 멈추고
(`MongoPrimaryController`), and injects network faults through Toxiproxy (`MongoPrimaryController`), Toxiproxy로 네트워크 장애를 넣는다(`ToxiproxyMongoNetworkFaultController`).
(`ToxiproxyMongoNetworkFaultController`). A single-node set is not sufficient for the election: it 노드 하나짜리 set으로는 선출을 시험할 수 없다. 선출이 일어나지 않으니 primary 교체에 기대는 보장은 모두
never holds one, so every guarantee that depends on a primary change goes untested. 시험되지 않는다.
The network faults need their own fixture (`MongoProxiedReplicaSetNode`) because a stopped container 네트워크 장애에는 따로 fixture(`MongoProxiedReplicaSetNode`)가 필요하다. 멈춘 container로는 만들 수 없기
cannot produce them. Stopping a node tells the client the write did not happen; cutting the *path* 때문이다. 노드를 멈추면 client는 쓰기가 일어나지 않았다는 것을 안다. 서버는 살려 둔 채 *경로*를 끊으면
while the server keeps running produces a client that cannot tell. `MongoNetworkFaultLaneTest` client는 알 수 없다. `MongoNetworkFaultLaneTest`는 같은 서버에 두 번 닿아 그 차이를 단언한다. 한 번은
asserts the difference by reaching the same server twice — once through the proxy, once directly: proxy를 거쳐, 한 번은 바로.
- **Partition**: the proxied client fails, the direct client finds the server healthy and the earlier - **분할**: proxy를 거친 client는 실패하고, 바로 닿은 client는 서버가 멀쩡하고 앞서 쓴 것이 그대로임을
write intact. The path was cut, not the server. 본다. 끊긴 것은 서버가 아니라 경로다.
- **Response loss**: the proxied client fails, and the direct client then finds the document - **응답 유실**: proxy를 거친 client는 실패하고, 바로 닿은 client는 문서가 *있음*을 본다. 쓰기는 적용됐고
*present*. The write applied and only the acknowledgement was lost — 확인 응답만 사라졌다. `DefaultMongoFailureClassifier`는 `WRITE_RESULT_UNKNOWN`을 돌려준다. 재시도했다면
`DefaultMongoFailureClassifier` returns `WRITE_RESULT_UNKNOWN`, and a retry would have inserted a 문서가 하나 더 생겼을 것이다.
second document.
One detail the lane depends on: the connection is warmed before the toxic is applied. On a cold lane이 기대는 세부가 하나 있다. toxic을 걸기 전에 connection을 먼저 데운다. 차가운 connection에서는
connection it is the driver's handshake whose response is dropped, so the write is never transmitted 응답이 사라지는 것이 driver의 handshake이므로 쓰기는 아예 전송되지 않는다. 그러면 `NOT_SENT`가 되어
— `NOT_SENT`, the opposite of the ambiguity being tested. 시험하려던 「결과를 모름」과 정반대가 된다.
+48 -55
View File
@@ -1,87 +1,80 @@
--- ---
title: Runbook — MongoDB unknown transaction commit result title: Runbook — MongoDB transaction commit 결과를 모름
category: mongodb category: mongodb
severity: P1 severity: P1
owner: oncall owner: oncall
last_updated: 2026-08-13 last_updated: 2026-08-13
status: active status: 운영
--- ---
# Runbook: unknown transaction commit result # Runbook: transaction commit 결과를 모름
Design §16, decision D-10, scenario `UNKNOWN_TRANSACTION_COMMIT_RESULT`. 설계서 §16, 결정 D-10, 시나리오 `UNKNOWN_TRANSACTION_COMMIT_RESULT`.
`MongoExecutionOutcome.TRANSACTION_COMMIT_UNKNOWN` means the commit **may have applied**. It is not a `MongoExecutionOutcome.TRANSACTION_COMMIT_UNKNOWN`은 commit이 **적용됐을 수 있다**는 뜻이다. 실패가 아니고,
failure and must never be reported to a caller as one. The single worst response is to re-run the 호출자에게 실패로 알리면 절대 안 된다. 가장 나쁜 대응은 transaction 본문을 다시 돌리는 것이다. commit이
transaction body: if the commit did apply, the body applies a second time. 적용됐다면 본문이 두 번 적용된다.
## Symptoms ## 증상
- `MongoTransactionCommitUnknownException` in logs. - 로그의 `MongoTransactionCommitUnknownException`.
- Metric `failureCategory=TRANSACTION_COMMIT_UNKNOWN`. - Metric `failureCategory=TRANSACTION_COMMIT_UNKNOWN`.
- Usually accompanies a primary election — see [failover.md](failover.md). - 보통 primary 선출과 함께 온다. [failover.md](failover.md)를 본다.
- Downstream reports of duplicated effects (double charge, double increment) are the symptom of this - 하류에서 효과가 두 번 났다는 보고(이중 결제, 이중 증가)는 이 상황 자체가 아니라 이것을 잘못 다룬 결과다.
being handled wrongly, not of the condition itself.
## Diagnosis ## 진단
1. **Confirm the platform did the right thing automatically.** 1. **플랫폼이 자동으로 옳게 했는지 확인한다.**
`MongoTransactionRetryCoordinator` retries the *commit only*, on the same session, within `MongoTransactionRetryCoordinator`는 같은 session에서 `MongoRetryBudget` 안에서 *commit만* 재시도한다.
`MongoRetryBudget`. A commit retry against an already-committed transaction is a no-op by design. 이미 commit된 transaction에 대한 commit 재시도는 설계상 아무 일도 하지 않는다. 대부분은 여기서 끝나고
Most occurrences resolve here and never reach a human. 사람에게 오지 않는다.
2. **If the budget was exhausted, determine the actual state.** The commit either applied or it did 2. **예산을 다 썼으면 실제 상태를 알아낸다.** commit은 적용됐거나 안 됐다. 짐작하지 말고 어느 쪽인지
not; you must find out which, not guess. 알아내야 한다.
- If the transaction body wrote a deterministic marker (an idempotency key, a business id, a - 본문이 결정적 표시(멱등 key, 업무 id, revision)를 썼으면 그것을 다시 읽는다. `MongoCommitReconciler`가
revision), read it back. That is exactly what `MongoCommitReconciler` does, and it is the 하는 일이 정확히 이것이고, 설계가 transaction에 표시를 쓰라고 요구하는 이유다.
reason the design requires transactions to write one. - 표시가 없으면 하류 흔적에서 되짚는다: outbox 행, 감사 기록, 외부 부수 효과. 비교할 것이 아무것도
- If there is no marker: reconstruct from a downstream artefact — an outbox row, an audit record, 없으면 그 transaction은 맞춰 볼 수 있게 설계되지 않은 것이고, 그것을 발견 사항으로 적는다.
an external side effect. If nothing exists to compare against, the transaction was not
designed to be reconcilable and that is the finding to record.
3. **Check whether the body was replayed.** Grep for a second execution with the same operation name 3. **본문이 다시 돌았는지 본다.** 같은 연산 이름과 correlation id로 두 번째 실행이 있는지 grep한다. 본문이
and correlation id. If the body ran twice, the effects need reversing, and the code path that 두 번 돌았으면 효과를 되돌려야 하고, 다시 돌린 코드 경로는 결함이다. 결과를 모르는 commit의 범위는
replayed it is a defect: an ambiguous commit is `COMMIT_ONLY` scope `COMMIT_ONLY`(`MongoRetryScope.COMMIT_ONLY`)이고 `BODY`가 아니다.
(`MongoRetryScope.COMMIT_ONLY`), never `BODY`.
## Action ## 조치
**Commit applied.** Nothing to do. Record the reconciliation. **commit이 적용됐다.** 할 일은 없다. 맞춰 본 결과를 기록한다.
**Commit did not apply.** Re-run the whole operation from the top — a new session, a new body **commit이 적용되지 않았다.** 연산 전체를 처음부터 다시 돌린다. 새 session, 새 본문 시도. 앞 시도가 흔적을
attempt. This is safe precisely because you established the previous attempt left no trace. 남기지 않았음을 확인했으므로 안전하다.
**Cannot determine.** Do not retry. Escalate. A blind retry here is a coin flip between "no effect" **알아낼 수 없다.** 재시도하지 않는다. 상향 보고한다. 여기서 확인 없이 재시도하면 「효과 없음」과
and "duplicate effect", and duplicates in a financial or notification path are worse than a delay. 「효과 두 번」 사이의 동전 던지기다. 결제나 알림 경로에서는 중복이 지연보다 나쁘다. 도메인이 지원하면
Freeze the affected entity if the domain supports it, and hand off with: operation name, correlation 대상 엔티티를 얼리고, 연산 이름, correlation id, 문서 id, 시간 구간, 확인한 것을 넘긴다.
id, document id, the time window, and what you checked.
**Recurring.** More than one an hour means the commit path is racing something structural — a **반복된다.** 한 시간에 한 번을 넘으면 commit 경로가 구조적인 무언가와 경쟁하고 있다. 관측한 선출 시간보다
`maxCommitTime` shorter than the observed election duration, an oversized transaction, or an 짧은 `maxCommitTime`, 너무 큰 transaction, 너무 작은 재시도 예산 같은 것이다. 예산이나 transaction 모양을
undersized retry budget. Fix the budget or the transaction shape; do not raise the retry count and 고친다. 재시도 횟수만 올리고 해결됐다고 하지 않는다.
call it resolved.
## Prevention ## 예방
- Every transaction body writes a deterministic marker that identifies its own commit. - 모든 transaction 본문은 자기 commit을 식별하는 결정적 표시를 쓴다.
- `maxCommitTime` exceeds the observed p99 election duration. - `maxCommitTime`은 관측한 선출 시간의 p99보다 길다.
- Callers surface the ambiguity to their own callers rather than mapping it to a generic 500 — an - 호출자는 결과를 모른다는 사실을 일반 500으로 바꾸지 않고 자기 호출자에게 그대로 올린다. 결과를 모르는
ambiguous outcome reported as a failure invites the caller to retry, which is the one thing that 것을 실패로 알리면 호출자가 재시도하고, 그것이 일어나면 안 되는 단 하나의 일이다.
must not happen. - 문서 하나의 atomic 연산을 먼저 쓴다(D-09). 문서 하나의 쓰기를 감싸려고만 있는 transaction은 이 실패
- Prefer a single-document atomic operation (D-09). A transaction that exists only to wrap one 모드를 쓸데없이 만든 것이다.
document write has invented this failure mode for nothing.
## Escalation ## 상향 보고
- Always P1 when the state cannot be determined and the operation has an external effect. - 상태를 알아낼 수 없고 연산에 외부 효과가 있으면 늘 P1.
- Page the service owner immediately; the database owner only if elections are the trigger. - 서비스 소유자를 바로 호출한다. DB 소유자는 선출이 원인일 때만 호출한다.
## Verification ## 확인
```bash ```bash
cd src cd src
./gradlew :adapter:outbound:persistence-mongo:mongoFailoverTest --console=plain ./gradlew :adapter:outbound:persistence-mongo:mongoFailoverTest --console=plain
``` ```
`MongoFailoverScenario.UNKNOWN_TRANSACTION_COMMIT_RESULT` runs this path against a real three-node `MongoFailoverScenario.UNKNOWN_TRANSACTION_COMMIT_RESULT`가 이 경로를 실제 노드 세 개짜리 set에서 돌리고,
set, and the coordinator test asserts the body is never replayed after a commit ambiguity. coordinator 테스트가 commit 결과를 모를 때 본문을 다시 돌리지 않음을 단언한다.
+89 -96
View File
@@ -1,137 +1,130 @@
# Schema, Index and Migration Guide # Schema, index, 마이그레이션 가이드
Design §21–§25, decision D-13. Indexes and validators are **declared** in a manifest and **applied** 설계서 §21–§25, 결정 D-13. index와 validator는 manifest에 **선언**하고, 명시적인 plane이 **적용**한다.
by an explicit plane. Automatic index creation in production is explicitly unsupported (§3.4): an 운영에서 index를 자동으로 만드는 것은 명시적으로 지원하지 않는다(§3.4). 큰 collection의 index 생성은 용량
index build on a large collection is a capacity event, and discovering it because a deployment 사건이다. 배포가 그것을 시작해서야 알게 되는 것은 운영 방식이라 할 수 없다.
started one is not an operating model.
## 1. The manifest is the source of truth ## 1. Manifest가 정본이다
`MongoManifestRegistry` holds one `MongoCollectionManifest` per collection, containing: `MongoManifestRegistry`는 collection마다 `MongoCollectionManifest`를 하나 가진다. 그 안에 있는 것:
- `MongoIndexManifest` — the declared indexes (`MongoIndexKey`, `MongoIndexDirection`, uniqueness, - `MongoIndexManifest` — 선언한 index(`MongoIndexKey`, `MongoIndexDirection`, unique 여부, partial
partial filter, collation) filter, collation)
- `MongoSchemaManifest` — the declared `$jsonSchema` validator - `MongoSchemaManifest` — 선언한 `$jsonSchema` validator
- `MongoMetadataOwnership` — who owns each observed object - `MongoMetadataOwnership` — 관측한 객체마다 누가 소유하는지
Ownership is the field that makes drift handling safe: drift(선언과 실제의 차이) 처리를 안전하게 만드는 것이 소유 필드다.
| Ownership | Owner | Droppable on drift | | 소유 | 소유자 | drift일 때 지워도 되나 |
|---|---|---| |---|---|---|
| `APPLICATION_MANAGED` | this manifest | yes | | `APPLICATION_MANAGED` | 이 manifest | 그렇다 |
| `SEARCH_MANAGED` | the search service | no | | `SEARCH_MANAGED` | 검색 서비스 | 아니다 |
| `ENCRYPTION_MANAGED` | Queryable Encryption | no | | `ENCRYPTION_MANAGED` | Queryable Encryption | 아니다 |
| `EXTERNAL` | someone else (a DBA, another service) | no | | `EXTERNAL` | 다른 누군가(DBA, 다른 서비스) | 아니다 |
A diff engine that does not know about ownership eventually proposes dropping 소유를 모르는 diff 엔진은 결국 `enxcol_.customers.esc`나 검색 index를 지우자고 한다. 「drift 도구가
`enxcol_.customers.esc` or a search index, and "the drift tool cleaned it up" is a very bad incident 정리했다」는 아주 나쁜 장애 요약이다.
summary.
## 2. Index diff and apply ## 2. Index diff와 적용
`MongoIndexDiffEngine` compares the manifest against `MongoIndexDescriptorView` observations and `MongoIndexDiffEngine`은 manifest를 `MongoIndexDescriptorView` 관측값과 비교해 `MongoIndexDiff`를 만든다:
produces a `MongoIndexDiff`: missing, extra, and *changed* (same name, different definition — 빠진 것, 남는 것, *바뀐* 것(이름은 같고 정의가 다름. MongoDB는 이것을 조용히 다시 만들지 않으므로 다시
MongoDB will not silently rebuild these, so they must be reported rather than re-issued). 내보내지 말고 보고해야 한다).
`MongoIndexApplyPolicy` decides what happens with a diff: `MongoIndexApplyPolicy`가 diff로 무엇을 할지 정한다.
| Policy | Behaviour | Environment | | 정책 | 동작 | 환경 |
|---|---|---| |---|---|---|
| `APPLY` | create what is missing | local / test | | `APPLY` | 빠진 것을 만든다 | local / test |
| `APPLY_WITH_DIFF` | create what is missing and report the rest | staging | | `APPLY_WITH_DIFF` | 빠진 것을 만들고 나머지는 보고한다 | staging |
| `DIFF_WITH_APPROVED_APPLY` | apply only what a human approved | production | | `DIFF_WITH_APPROVED_APPLY` | 사람이 승인한 것만 적용한다 | production |
| `REPORT_ONLY` | never write | audit | | `REPORT_ONLY` | 절대 쓰지 않는다 | 감사 |
Dropping is never implicit. `MongoIndexRetirementPlan` moves an index through 삭제는 암묵적으로 일어나지 않는다. `MongoIndexRetirementPlan`이 index를 `MongoIndexRetirementState`로
`MongoIndexRetirementState` — declared → hidden → observed-unused → droppable — and each transition 옮긴다 — 선언됨 → 숨김 → 안 쓰임 관측 → 지워도 됨 — 그리고 단계마다 따로 배포한다. index를 숨기면
is a separate deployment. Hiding an index makes the planner ignore it while keeping it maintained, so planner는 무시하지만 유지는 계속된다. 그래서 뜻밖의 회귀는 명령 하나로 되돌린다. 지운 것은 그렇게 되돌릴
an unexpected regression is one command to undo. Dropping it is not. 수 없다.
## 3. Validators ## 3. Validator
`MongoValidatorDescriptor` carries the `$jsonSchema`, a `MongoValidationLevel` `MongoValidatorDescriptor`는 `$jsonSchema`, `MongoValidationLevel`(`OFF` / `MODERATE` / `STRICT`),
(`OFF` / `MODERATE` / `STRICT`) and a `MongoValidationAction`. `MongoValidationAction`을 가진다.
**Stable validation actions are `error` and `warn` only.** `errorAndLog` is not part of the Stable **Stable validation action은 `error`와 `warn`뿐이다.** `errorAndLog`는 MongoDB 7.0이나 8.0에서 Stable 계약에
contract on MongoDB 7.0 or 8.0 and the descriptor refuses it. 들지 않고, descriptor가 거부한다.
`MongoValidatorDiffEngine` produces a `MongoValidatorDiff`; `MongoValidatorApplyPolicy` gates the `MongoValidatorDiffEngine`이 `MongoValidatorDiff`를 만들고 `MongoValidatorApplyPolicy`가 적용을 막거나
apply. Tightening a validator on a collection with existing data is the dangerous direction: introduce 허락한다. 데이터가 이미 있는 collection의 validator를 조이는 것이 위험한 방향이다. `warn` + `MODERATE`로
it as `warn` + `MODERATE`, confirm the warning count is zero, then promote to `error` + `STRICT` in a 넣고, 경고 수가 0인지 확인한 뒤, 두 번째 배포에서 `error` + `STRICT`로 올린다.
second deployment.
## 4. TTL ## 4. TTL
D-13: TTL is **physical cleanup**, nothing else. D-13: TTL은 **물리적 정리**일 뿐이다.
`MongoTtlIndexDescriptor` declares the field and `expireAfterSeconds`. `MongoTtlPolicyValidator` `MongoTtlIndexDescriptor`가 필드와 `expireAfterSeconds`를 선언한다. `MongoTtlPolicyValidator`가
enforces what `MongoTtlPolicy` allows, and `MongoExpirationAccessPolicy` states the rule that matters: `MongoTtlPolicy`가 허락하는 것을 강제하고, `MongoExpirationAccessPolicy`가 중요한 규칙을 말한다.
> A document's presence is not authorization, and its absence is not a deadline. > 문서가 있다고 권한이 있는 것이 아니고, 문서가 없다고 기한이 지난 것도 아니다.
The TTL monitor runs about once a minute and deletes in batches, so a document can outlive its TTL monitor는 대략 1분에 한 번 돌고 묶어서 지운다. 그래서 부하가 있으면 문서가 만료 후 몇 분에서 몇 시간
expiry by minutes to hours under load. Consequences: 더 남는다. 따라서:
- Access control must check the expiry field, not the document's existence. A still-present expired - 접근 제어는 문서가 있는지가 아니라 만료 필드를 본다. 아직 남아 있는 만료된 session은 유효한 문서이자
session is a valid document and an invalid session. 무효한 session이다.
- Business scheduling must not be built on TTL. If something must happen at a time, schedule it. - 업무 일정을 TTL 위에 세우지 않는다. 정해진 때에 일어나야 하는 일이면 일정을 잡는다.
- A TTL field must be a BSON date. A TTL index on a string silently never deletes anything. - TTL 필드는 BSON date여야 한다. 문자열에 건 TTL index는 조용히 아무것도 지우지 않는다.
## 5. Migrations ## 5. 마이그레이션
`MongoMigrationRunner` executes `MongoMigration` units with: `MongoMigrationRunner`는 다음과 함께 `MongoMigration` 단위를 실행한다.
- `MongoMigrationId` — ordered, unique - `MongoMigrationId` — 순서가 있고 유일하다
- `MongoMigrationChecksum` — content hash; a changed checksum for an applied id is a hard failure, not - `MongoMigrationChecksum` — 내용 hash. 이미 적용한 id의 checksum이 바뀌면 다시 돌리지 않고 바로 실패한다.
a re-run. Editing an applied migration means two environments ran different code under the same id. 적용한 마이그레이션을 고치면 두 환경이 같은 id로 다른 코드를 돌린 것이 된다.
- `MongoMigrationLedger` — what has been applied - `MongoMigrationLedger` — 무엇이 적용됐는지
- `MongoMigrationLock` — one runner at a time; a rolling deploy starts several instances at once - `MongoMigrationLock` — 한 번에 runner 하나. rolling 배포는 인스턴스 여럿을 한꺼번에 띄운다
- `MongoMigrationPrecondition` / `MongoMigrationPostcondition` — checked before and after; a migration - `MongoMigrationPrecondition` / `MongoMigrationPostcondition` — 전후로 확인한다. 자기 결과를 확인하지
that cannot verify its own result is a migration whose failure is discovered by a customer 못하는 마이그레이션은 실패를 고객이 발견한다
- `MongoMigrationCheckpoint` — a resumable position for a backfill - `MongoMigrationCheckpoint` — backfill을 이어 할 수 있는 위치
`MongoMigrationResult` reports applied / incomplete / dry-run with the reason. `INCOMPLETE` is not a `MongoMigrationResult`는 applied / incomplete / dry-run과 그 이유를 보고한다. `INCOMPLETE`는 실패가 아니다.
failure: a rate-limited backfill that ran out of its time budget has done real work and stored a 속도를 제한한 backfill이 시간 예산을 다 썼으면 실제 일을 했고 checkpoint를 저장했다. 그것을 실패로 알리면
checkpoint, and reporting it as failed would send the next run back to the beginning. 다음 실행이 처음으로 돌아간다.
`MongoCollectionMigrationLedger` and `MongoCollectionMigrationLock` are the MongoDB-backed `MongoCollectionMigrationLedger`와 `MongoCollectionMigrationLock`이 MongoDB에 기대는 구현이다. 빠지면 안
implementations. Two details are load-bearing and only exist on a server: 되는 세부가 둘 있고, 둘 다 서버에만 있다.
- The ledger's **unique index** on the migration id, created by `ensureIndexes()`. Without it, two - `ensureIndexes()`가 만드는 ledger의 마이그레이션 id **unique index**. 이것이 없으면 「아직 적용 안 됨」
runners that both pass the "not applied yet" read both insert, and the ledger then reports one 읽기를 둘 다 통과한 runner 둘이 둘 다 insert한다. 그러면 ledger는 마이그레이션 하나가 checksum 둘로 두 번
migration applied twice with two checksums — indistinguishable from tampering. 적용됐다고 보고한다. 조작과 구분할 수 없다.
- The lease is taken with **one conditional update**, not read-then-write. A filter matching only a - lease는 읽고-쓰기가 아니라 **조건부 update 한 번**으로 잡는다. 비었거나 만료된 lease에만 맞는 filter를
free or expired lease lets the server pick the winner; two runners that each read "free" and then 쓰면 서버가 승자를 고른다. runner 둘이 각자 「비었음」을 읽고 쓰면 둘 다 자기가 잡았다고 믿는다.
write would both believe they hold it.
The lease expires so a runner killed mid-migration does not block every future deployment, and lease에는 만료가 있다. 그래야 마이그레이션 도중 죽은 runner가 이후 모든 배포를 막지 않는다. batch 사이의
`refresh` between batches is what proves the holder is still alive. `refresh`가 lease를 가진 쪽이 아직 살아 있다는 증거다.
### Backfills restart, they do not restart-from-zero ### Backfill은 이어서 시작하고, 처음부터 다시 하지 않는다
A long backfill will be interrupted — a deploy, an OOM, a node replacement. The checkpoint records 긴 backfill은 끊긴다. 배포, OOM, 노드 교체. checkpoint가 마지막으로 끝낸 key를 적어 두므로 다시 시작하면
the last completed key so the restart continues rather than re-processing from the beginning. 처음부터 다시 처리하지 않고 이어 간다. testkit의 `MongoBackfillRestartFixture`가 정확히 이것을 단언한다:
`MongoBackfillRestartFixture` in the testkit asserts exactly this: kill mid-run, restart, and the 도중에 죽이고 다시 시작해도 결과가 끊기지 않은 실행과 같고, 끝낸 일을 다시 적용하지 않는다.
result is identical to the uninterrupted run and does not re-apply completed work.
### Flamingock ### Flamingock
`FlamingockMongoMigrationAdapter` bridges to Flamingock through the platform-owned `FlamingockMongoMigrationAdapter`가 플랫폼이 소유한 `FlamingockChangeUnitView`를 거쳐 Flamingock에
`FlamingockChangeUnitView`, with `FlamingockLedgerAdapter` and `FlamingockLockAdapter` mapping the 잇는다. `FlamingockLedgerAdapter`와 `FlamingockLockAdapter`가 ledger와 lock을 대응시킨다. 공개 계약은
ledger and lock. The public contract does not reference Flamingock types, so the provider can be Flamingock 타입을 참조하지 않으므로 마이그레이션을 건드리지 않고 provider를 바꿀 수 있다.
replaced without touching a migration.
## 6. Ordering with deployments ## 6. 배포와의 순서
``` ```text
1. Add the index (hidden if it is large) -> deployment N 1. index를 더한다(크면 숨긴 채로) -> 배포 N
2. Unhide / verify usage -> deployment N+1 2. 숨김을 풀고 쓰이는지 확인한다 -> 배포 N+1
3. Ship code that depends on the index -> deployment N+1 3. 그 index에 기대는 코드를 내보낸다 -> 배포 N+1
4. Backfill data -> migration, resumable 4. 데이터를 backfill한다 -> 마이그레이션, 이어 할 수 있음
5. Tighten the validator from warn to error -> deployment N+2 5. validator를 warn에서 error로 조인다 -> 배포 N+2
6. Retire the old index through the retirement states -> deployments N+3… 6. 옛 index를 은퇴 단계에 따라 내린다 -> 배포 N+3…
``` ```
Each step is independently reversible. A deployment that adds an index and the code that requires it 단계마다 따로 되돌릴 수 있다. index와 그 index가 필요한 코드를 같은 배포에 넣으면 안전하게 되돌릴 길이
at the same time has no safe rollback: rolling back the code leaves the index build running, and 없다. 코드를 되돌리면 index 생성은 계속 돌고, index를 되돌리면 아직 절반의 인스턴스에서 도는 코드가 깨진다.
rolling back the index breaks the code that is still live on half the fleet.
+85 -92
View File
@@ -1,148 +1,141 @@
# Security and Observability # 보안과 관측
Design §26–§28, decision D-05. The application plane and the admin plane are different credentials on 설계서 §26–§28, 결정 D-05. 애플리케이션 plane과 admin plane은 다른 client 위의 다른 credential이다.
different clients, and telemetry never becomes an exfiltration path. 그리고 telemetry는 절대 데이터 유출 경로가 되지 않는다.
## 1. Roles ## 1. Role
`MongoPrincipalRole` — one credential per role, least privilege: `MongoPrincipalRole` — role마다 credential 하나, 최소 권한:
| Role | Grants | | Role | 주는 권한 |
|---|---| |---|---|
| `APP_READ` | `find` on allowlisted collections | | `APP_READ` | 허용 목록 collection의 `find` |
| `APP_WRITE` | `insert`, `update`, `delete` on allowlisted collections | | `APP_WRITE` | 허용 목록 collection의 `insert`, `update`, `delete` |
| `CHANGE_STREAM` | `changeStream`, `find` | | `CHANGE_STREAM` | `changeStream`, `find` |
| `MIGRATION` | index and validator management on the target collections | | `MIGRATION` | 대상 collection의 index·validator 관리 |
| `SEARCH_ADMIN` | search index management | | `SEARCH_ADMIN` | 검색 index 관리 |
| `SHARD_ADMIN` | shard key operations | | `SHARD_ADMIN` | shard key 작업 |
| `ENCRYPTION_ADMIN` | key vault access | | `ENCRYPTION_ADMIN` | key vault 접근 |
| `DBA` | the human plane; never used by an application | | `DBA` | 사람의 plane. 애플리케이션은 절대 쓰지 않는다 |
`MongoSecurityProfileValidator` checks the profile at startup. `forbiddenPrivilegesHeld()` names the `MongoSecurityProfileValidator`가 시작할 때 profile을 검사한다. `forbiddenPrivilegesHeld()`는 profile이 갖고
privileges the profile holds and must not — the validator reports *which* one, because "your 있으면 안 되는데 가진 권한의 이름을 댄다. validator가 *어느* 권한인지 말하는 이유는, 이름 없이 「credential
credential is over-privileged" without a name is an unactionable finding. 권한이 너무 크다」고만 하면 대응할 수 없는 발견이기 때문이다.
The privileges that must never appear on an application credential: `dropDatabase`, 애플리케이션 credential에 절대 있으면 안 되는 권한: `dropDatabase`, `dropCollection`, `shutdown`, `killop`,
`dropCollection`, `shutdown`, `killop`, `root`, `__system`, `dbOwner`, `userAdminAnyDatabase`. `root`, `__system`, `dbOwner`, `userAdminAnyDatabase`.
## 2. Credentials are references, not values ## 2. Credential은 값이 아니라 참조다
`MongoCredentialReference` holds a `secret://…` reference plus the role. The reference is resolved at `MongoCredentialReference`는 `secret://…` 참조와 role을 가진다. 참조는 연결할 때 secret provider가 푼다.
connection time by the secret provider; the password is never a property value, a log field, or a 비밀번호는 속성 값, 로그 필드, stack trace에 남을 수 있는 생성자 인자가 절대 되지 않는다.
constructor argument that could end up in a stack trace.
`MongoCredentialRotationPolicy` states the rotation contract: overlapping validity, a drain window, `MongoCredentialRotationPolicy`가 교체 계약을 말한다: 유효 기간이 겹치고, 비우는 구간(drain window)이 있고,
and a rotation that never requires a restart. `MongoClientGenerationRegistry` implements the swap — 교체에 재시작이 필요 없다. `MongoClientGenerationRegistry`가 바꿔 끼우기를 구현한다. 새
a new `MongoClientGeneration` starts serving new operations while the previous generation is `MongoClientGeneration`이 새 연산을 받는 동안 앞 세대는 `markDraining()` 상태로 처리 중인 연산이 끝날 때까지
`markDraining()` until its in-flight operations finish. Killing the old client immediately fails every 남는다. 옛 client를 바로 죽이면 처리 중인 요청이 모두 실패한다. 세대 없는 교체가 장애인 이유다.
in-flight request, which is why rotation without generations is an outage.
Rotation is a failover scenario in the release gate (`MongoFailoverScenario.CREDENTIAL_ROTATION`), 교체는 릴리스 게이트의 failover 시나리오(`MongoFailoverScenario.CREDENTIAL_ROTATION`)다. 잘 되기를 바라는
not a runbook step people hope works. runbook 단계가 아니다.
## 3. TLS and connection policy ## 3. TLS와 연결 정책
`MongoSecurityProfile.production(...)` requires TLS and refuses `tlsAllowInvalidCertificates` / `MongoSecurityProfile.production(...)`은 TLS를 요구하고 `tlsAllowInvalidCertificates` /
`tlsAllowInvalidHostnames`. `MongoSecurityProfile.local(...)` exists so a developer does not have to `tlsAllowInvalidHostnames`를 거부한다. `MongoSecurityProfile.local(...)`이 있는 것은 개발자가 container에
weaken the production factory to get a container to connect; the startup validator refuses a local 붙으려고 production factory를 약하게 만들지 않게 하려는 것이다. 시작 validator는 운영 runtime profile에서
profile on a production runtime profile. local profile을 거부한다.
## 4. Admin plane (D4) ## 4. Admin plane (D4)
`MongoAdminGateway` is the only path to `MongoAdminOperation`, and it runs on the D4 client with the `MongoAdminGateway`가 `MongoAdminOperation`으로 가는 유일한 길이고, 애플리케이션 것이 아니라 DBA 범위
DBA-scoped credential — not the application's. credential을 쓰는 D4 client에서 돈다.
- `MongoAdminAuthorization` checks the caller's role against the operation. - `MongoAdminAuthorization`이 호출자의 role을 연산과 대조한다.
- `MongoAdminRuntimeGuard` refuses high-risk operations (`highRisk()`) unless the runtime profile - `MongoAdminRuntimeGuard`는 runtime profile이 명시적으로 허락하지 않으면 위험한 연산(`highRisk()`)을
explicitly permits them; a `dropCollection` reachable from a running application is a data-loss 거부한다. 실행 중인 애플리케이션에서 닿을 수 있는 `dropCollection`은 호출 코드를 아무리 잘 검토했어도
vector regardless of how well-reviewed the calling code is. 데이터 손실 경로다.
- `MongoAdminAuditRecord` records who ran what, when and against which collection profile — before - `MongoAdminAuditRecord`가 누가 무엇을, 언제, 어느 collection profile에 돌렸는지 실행 *전에* 기록한다.
execution, so a failed attempt is recorded too. 그래서 실패한 시도도 남는다.
The native capability gateway (D3) refuses any admin-category command, so there is no path from the native capability gateway(D3)는 admin 분류의 명령을 모두 거부한다. 그래서 애플리케이션 plane에서 admin
application plane into the admin plane. plane으로 가는 길은 없다.
## 5. Observability tags ## 5. 관측 tag
`MongoObservationConvention` allowlists exactly eight tag names: `MongoObservationConvention`은 tag 이름을 정확히 여덟 개만 허용한다.
``` ```
mongoProfile, databaseProfile, collectionProfile, operationName, mongoProfile, databaseProfile, collectionProfile, operationName,
operationType, result, failureCategory, consistencyProfile operationType, result, failureCategory, consistencyProfile
``` ```
and explicitly forbids: 그리고 다음을 명시적으로 금지한다.
``` ```
documentId, rawTenantId, tenantId, dynamicCollectionName, queryParameter, documentId, rawTenantId, tenantId, dynamicCollectionName, queryParameter,
query, fullBson, resumeToken, shardKeyValue, plaintextPII, credential query, fullBson, resumeToken, shardKeyValue, plaintextPII, credential
``` ```
Two reasons, and both matter. Cardinality: a tag whose values are document ids produces one time 이유는 둘이고 둘 다 중요하다. 가짓수: 값이 문서 id인 tag는 문서마다 시계열 하나를 만들고, 그렇게 metric
series per document, which is how a metrics backend falls over. Confidentiality: a metric label is 저장소가 쓰러진다. 기밀성: metric label은 DB와 접근 모델이 다른 시스템이 저장하고, 보내고, 보관한다.
stored, shipped and retained by systems with a different access model than the database. `requireAllowed(tagName)`는 목록 밖의 것에 예외를 던진다. 그래서 새 tag는 서비스 코드의 한 줄이 아니라
`requireAllowed(tagName)` throws on anything outside the list, so a new tag is a deliberate change to convention의 의도적인 변경이 된다.
the convention rather than a line in a service.
`MicrometerMongoOperationObserver` implements the `MongoOperationObserver` port; `MicrometerMongoOperationObserver`가 `MongoOperationObserver` port를 구현한다. 기본값은
`NoOpMongoOperationObserver` is the default so observation is opt-in and never a hard dependency. `NoOpMongoOperationObserver`라서 관측은 켜야 생기고 필수 의존이 되지 않는다.
## 6. Driver-native listeners ## 6. Driver 자체 listener
`MongoDriverObservabilityConfiguration` registers three driver listeners, because they answer `MongoDriverObservabilityConfiguration`은 driver listener 셋을 등록한다. 애플리케이션 수준 timer로는 답할 수
questions the application-level timer cannot: 없는 질문에 답하기 때문이다.
| Listener | Answers | | Listener | 답하는 질문 |
|---|---| |---|---|
| `MongoCommandObservationListener` | How long did the *server* take, versus how long the caller waited? | | `MongoCommandObservationListener` | *서버*가 걸린 시간과 호출자가 기다린 시간은 각각 얼마인가? |
| `MongoPoolObservationListener` | Was the wait time connection checkout rather than query execution? | | `MongoPoolObservationListener` | 기다린 시간이 query 실행이 아니라 connection checkout이었나? |
| `MongoSdamObservationListener` | Did the topology change — an election, a node removed — during the window? | | `MongoSdamObservationListener` | 그 구간에 토폴로지가 바뀌었나 — 선출, 노드 빠짐? |
Without pool and SDAM events, every failover looks like "the database got slow", and the difference pool과 SDAM 이벤트가 없으면 모든 failover가 「DB가 느려졌다」로 보이고, 「pool을 늘려야 한다」와
between "we need a bigger pool" and "we lost a primary" is invisible. 「primary를 잃었다」의 차이가 보이지 않는다.
## 7. Command redaction ## 7. 명령 가리기
`MongoObservationRedactor.describe(commandName)`: `MongoObservationRedactor.describe(commandName)`:
- Authentication and user-management commands (`authenticate`, `saslStart`, `saslContinue`, - 인증·사용자 관리 명령(`authenticate`, `saslStart`, `saslContinue`, `getnonce`, `createUser`,
`getnonce`, `createUser`, `updateUser`, `copydb*`) render as `<redacted>` — their arguments carry `updateUser`, `copydb*`)은 `<redacted>`로 보인다. 인자에 credential과 key 재료가 있다.
credentials and key material. - 구조 명령(`ping`, `hello`, `buildInfo`, `listCollections`, `listIndexes`, `collStats`)은 이름으로
- Structural commands (`ping`, `hello`, `buildInfo`, `listCollections`, `listIndexes`, `collStats`) 보인다. 인자에 데이터가 없다.
render by name; their arguments are not data-bearing. - 나머지는 모두 `name(...)`으로 보인다. 명령은 보이고 filter나 문서는 보이지 않는다.
- Everything else renders as `name(...)`: you get the command, never the filter or the document.
`isAlwaysRedacted(...)` is the assertion hook so a test can prove no logging path can render an auth `isAlwaysRedacted(...)`는 테스트가 어떤 로그 경로도 인증 명령의 인자를 그리지 못함을 증명하는 단언 hook이다.
command's arguments.
## 8. Startup validation ## 8. 시작 검증
`MongoStartupValidator` runs at context refresh, before the first request: `MongoStartupValidator`는 context refresh 때, 첫 요청 전에 돈다.
1. `MongoTopologyProbe` reports the actual `MongoTopology` and its `MongoCapabilitySet`. 1. `MongoTopologyProbe`가 실제 `MongoTopology`와 그 `MongoCapabilitySet`을 보고한다.
2. Every profile's declared topology must match it, and a production profile on `STANDALONE` fails. 2. profile마다 선언한 토폴로지가 그것과 맞아야 하고, `STANDALONE` 위의 production profile은 실패한다.
3. With `platform.transactions=true`, the probe must report `TRANSACTION` as `STABLE`; on 3. `platform.transactions=true`이면 probe가 `TRANSACTION`을 `STABLE`로 보고해야 한다. `STANDALONE`에서는
`STANDALONE` it does not, so startup fails. 그렇지 않으므로 시작이 실패한다.
4. `MongoSecurityProfileValidator` checks credentials and TLS, and that the admin credential differs 4. `MongoSecurityProfileValidator`가 credential과 TLS, 그리고 admin credential이 runtime credential과
from the runtime one; the `MongoSchemaVersionRange` must not be inverted. 다른지를 검사한다. `MongoSchemaVersionRange`는 거꾸로면 안 된다.
5. `MongoPlatformHealthIndicator` reports topology mismatch and secondary availability for the 5. `MongoPlatformHealthIndicator`가 readiness probe에 토폴로지 불일치와 secondary 가용성을 보고한다.
readiness probe.
A misconfiguration found at startup costs a failed deploy. The same misconfiguration found at runtime 시작할 때 발견한 설정 오류는 배포 한 번 실패로 끝난다. 같은 오류를 실행 중에 발견하면 장애가 되고, 실패한
costs an incident, and the failing operation is rarely the one that reveals the cause. 연산이 원인을 드러내는 일은 드물다.
## 9. How the security lane proves any of this ## 9. 보안 lane이 이것을 어떻게 증명하나
```bash ```bash
cd src cd src
./gradlew :adapter:outbound:persistence-mongo:mongoSecurityIntegrationTest --console=plain ./gradlew :adapter:outbound:persistence-mongo:mongoSecurityIntegrationTest --console=plain
``` ```
The lane runs against `MongoAuthenticatedReplicaSetContainer`, which starts mongod with `--auth` and a 이 lane은 `MongoAuthenticatedReplicaSetContainer`에서 돈다. 이것은 `--auth`와 생성한 keyfile로 mongod를
generated keyfile. That detail is the whole lane: Testcontainers' `MongoDBContainer` starts mongod 띄운다. 그 세부가 lane의 전부다. Testcontainers의 `MongoDBContainer`는 mongod를 `--auth` *없이* 띄운다.
*without* `--auth`, so users created on it all have every privilege and a least-privilege assertion 그 위에서 만든 사용자는 모두 모든 권한을 가지므로, role이 아무리 틀려도 최소 권한 단언이 통과한다. 실패할
passes no matter how wrong the roles are. A security test that cannot fail is not a security test. 수 없는 보안 테스트는 보안 테스트가 아니다.
What the lane asserts is the refusal: the `read` role's insert is rejected, and the application role's lane이 단언하는 것은 거부다. `read` role의 insert가 거부되고, 애플리케이션 role의 `dropDatabase`가
`dropDatabase` is rejected. Then it checks that `MongoSecurityProfileValidator` names the same 거부된다. 그다음 `MongoSecurityProfileValidator`가 서버가 방금 거부한 바로 그 권한을 이름으로 대는지 본다.
privilege the server just refused.
+65 -65
View File
@@ -1,91 +1,91 @@
# MongoDB Platform — Support Matrix # MongoDB 플랫폼 — 지원 매트릭스
Design §4. This file records what the platform is *certified* on, not what it happens to run on. 설계서 §4. 이 파일은 플랫폼이 우연히 돌아가는 환경이 아니라 *인증한* 환경을 적는다. 이 표에 없는 구성은
A configuration absent from this table is unsupported until someone runs the gate against it and 누군가 그 구성으로 게이트를 돌리고 행을 더하기 전까지 지원하지 않는다.
adds a row.
## 1. Runtime baseline ## 1. 런타임 기준
| Component | Version | Policy | | 구성 요소 | 버전 | 정책 |
|---|---|---| |---|---|---|
| Java | 21 | Repository runtime baseline. | | Java | 21 | 저장소 런타임 기준. |
| Spring Boot | 4.0.0 | BOM-managed. Individual driver overrides are forbidden. | | Spring Boot | `src/gradle/libs.versions.toml`의 `springBoot` | BOM이 관리한다. driver를 따로 덮어쓰는 것은 금지한다. |
| Spring Data MongoDB | 5.0.0 | Repository and `MongoTemplate` integration. Version comes from the Boot BOM. | | Spring Data MongoDB | Boot BOM이 정한다 | repository와 `MongoTemplate` 통합. |
| MongoDB Java Driver | 5.6.1 | BOM-managed. Never pinned directly in the module. | | MongoDB Java Driver | Boot BOM이 정한다 | 모듈에서 직접 고정하지 않는다. |
| Micrometer | 1.16.0 | Driver-native observability. | | Micrometer | Boot BOM이 정한다 | driver 자체 관측. |
| Testcontainers | 2.0.2 | Replica-set, failover, migration and compatibility lanes. | | Testcontainers | Boot BOM이 정한다 | replica set, failover, migration, compatibility lane. |
The design's baseline is Spring Boot 4.1.x / Spring Data MongoDB 5.1.x. This repository is on BOM이 정한 실제 버전은 leaf의 잠금 파일 `src/adapter/outbound/persistence-mongo/gradle.lockfile`에 있다.
4.0.0 / 5.0.0, so the platform targets only the API surface common to both. See 버전을 이 표에 옮겨 적지 않는다. 옮겨 적은 숫자는 다음 업그레이드에서 틀린 글이 된다.
[repository-adaptation.md](repository-adaptation.md) §3.
## 2. Server versions 설계의 기준은 Spring Boot 4.1 계열 / Spring Data MongoDB 5.1 계열이다. 이 저장소는 Spring Boot 4.0 계열 /
Spring Data MongoDB 5.0 계열이므로, 플랫폼은 둘에 공통인 API 면만 쓴다.
[repository-adaptation.md](repository-adaptation.md) §3을 본다.
| Lane | Version | Pinned image | Gradle task | ## 2. 서버 버전
| Lane | 버전 | 고정한 이미지(key) | Gradle task |
|---|---|---|---| |---|---|---|---|
| Primary certification | MongoDB 8.0 | `mongo:8.0.16` | `mongoReplicaSetTest`, `mongoFailoverTest` | | 주 인증 | MongoDB 8.0 | `mongo-8` | `mongoReplicaSetTest`, `mongoFailoverTest` |
| Compatibility | MongoDB 7.0 | `mongo:7.0.28` | `mongoCompatibilityTest` | | 호환성 | MongoDB 7.0 | `mongo-7` | `mongoCompatibilityTest` |
| Network fault injection | — | `ghcr.io/shopify/toxiproxy:2.12.0` | `mongoFailoverTest` | | 네트워크 장애 주입 | — | `toxiproxy` | `mongoFailoverTest` |
Images are pinned, never `latest`: a mutable tag means the certification result describes whatever 이미지는 고정하고 `latest`를 쓰지 않는다. 바뀌는 tag를 쓰면 인증 결과는 행에 적은 버전이 아니라 그날 아침
was pulled that morning, not the version in the row. Override with 받은 무언가를 설명한다. 이미지의 정본은 `src/config/testing/container-images.properties`다. 표의 key마다
`-PmongoPrimaryImage=…` / `-PmongoCompatibilityImage=…` when testing a new patch level, and update digest와 그 digest의 tag(주석)가 거기 있다. patch 버전은 이 표에 옮겨 적지 않는다. 새 patch 버전을 시험할 때는
the row once the gate passes. `-PmongoPrimaryImage=…` / `-PmongoCompatibilityImage=…`로 덮어쓰고, 게이트가 통과하면 그 파일을 고친다.
`MongoVersionMatrix.standard()` is the machine-readable form of this table; a version outside it `MongoVersionMatrix.standard()`가 이 표의 기계용 형태다. 그 밖의 버전은 `certifies()`에서 실패한다.
fails `certifies()`.
## 3. Topologies ## 3. 토폴로지
| Topology | Status | What is certified | What is not | | 토폴로지 | 상태 | 인증하는 것 | 인증하지 않는 것 |
|---|---|---|---| |---|---|---|---|
| Standalone | **Smoke only** | Basic CRUD and mapping. | Not a production profile and never counts as Stable release evidence (D-03). A production profile, or `platform.transactions=true`, on a Standalone server is refused at startup by `MongoStartupValidator`. | | Standalone | **smoke만** | 기본 CRUD와 매핑. | 운영 profile이 아니고 Stable 릴리스 증거로 세지 않는다(D-03). Standalone 서버 위의 운영 profile이나 `platform.transactions=true`는 `MongoStartupValidator`가 시작할 때 거부한다. |
| Single-node replica set | **Local default** (D-02) | Transactions, retryable writes, change streams — the same semantics as production. | Elections. A single-node set never holds one, so failover behaviour is untested here. | | 노드 하나짜리 replica set | **로컬 기본값**(D-02) | transaction, retryable write, change stream — 운영과 같은 의미. | 선출. 노드 하나짜리 set은 선출을 하지 않으므로 여기서는 failover 동작을 시험하지 않는다. |
| 3-node replica set | **Stable production gate** | Everything above plus primary failover and unknown-commit handling. | Shard routing. | | 노드 세 개짜리 replica set | **Stable 운영 게이트** | 위의 모든 것과 primary failover, commit 결과를 모를 때의 처리. | shard 라우팅. |
| Sharded cluster | **Advanced gate** | Shard-key routing classification, scatter-gather refusal, `admin` plane operations. | Not included in the Stable gate. | | Sharded cluster | **Advanced 게이트** | shard key 라우팅 분류, scatter-gather 거부, `admin` plane 작업. | Stable 게이트에 들지 않는다. |
| Atlas / provider-managed | **Not certified** | Encryption against the actual target deployment is the adopter's evidence to produce. | Search and vector search have no implementation in this leaf; a native `$search` command can only go through `PolicyAwareMongoNativeGateway` as a registered D3 operation. | | Atlas / provider 관리형 | **인증 안 함** | 실제 대상 배포에서의 암호화는 도입하는 쪽이 만들 증거다. | 검색과 vector 검색은 이 leaf에 구현이 없다. native `$search` 명령은 등록한 D3 연산으로 `PolicyAwareMongoNativeGateway`를 거쳐야만 갈 수 있다. |
## 4. Stable API and client generations ## 4. Stable API와 client 세대
| Plane | Stable API | Purpose | | Plane | Stable API | 용도 |
|---|---|---| |---|---|---|
| D1 Standard document persistence | V1, `apiStrict=true` | Repositories, typed queries, atomic updates, optimistic revision. | | D1 표준 문서 영속성 | V1, `apiStrict=true` | repository, 타입 있는 query, atomic update, 낙관적 revision. |
| D2 Advanced document operations | V1, `apiStrict=true` | `MongoTemplate`, transactions, bulk, aggregation, keyset cursors. | | D2 고급 문서 연산 | V1, `apiStrict=true` | `MongoTemplate`, transaction, bulk, aggregation, keyset cursor. |
| D3 Explicit Mongo capability | Not strict | Native BSON, CSFLE/QE, shard-aware operations — each behind a registered capability. | | D3 명시적 Mongo capability | strict 아님 | native BSON, CSFLE/QE, shard를 아는 연산 — 각각 등록한 capability 뒤에 있다. |
| D4 Admin plane | Not strict | Collection, validator, index, migration, shard and repair commands. Separate credential, separate client. | | D4 Admin plane | strict 아님 | collection, validator, index, migration, shard, repair 명령. credential도 client도 따로다. |
D3 is not a raw-client escape. Every call passes capability registration → database profile → D3는 날것의 client로 빠지는 출구가 아니다. 모든 호출은 이 순서대로 지나간다: capability 등록 → database
collection allowlist → operation name → timeout → consistency profile → result limit → trace → profile → collection 허용 목록 → 연산 이름 → timeout → 일관성 profile → 결과 상한 → trace → 가리기 → 명령
redaction → command category → D4 refusal, in that order. 분류 → D4 거부.
## 5. Validation actions ## 5. Validation action
Stable validation actions are `error` and `warn`. `errorAndLog` is **not** part of the Stable Stable validation action은 `error`와 `warn`이다. `errorAndLog`는 7.0이나 8.0에서 Stable 계약에 들지
contract on 7.0 or 8.0 and `MongoValidatorDescriptor` refuses it. **않고**, `MongoValidatorDescriptor`가 거부한다.
## 6. Explicitly unsupported ## 6. 명시적으로 지원하지 않는 것
Per design §3.4, none of the following is provided, and adding one is a design change rather than a 설계 §3.4에 따라 아래는 하나도 제공하지 않는다. 하나라도 더하는 것은 기능 요청이 아니라 설계 변경이다.
feature request:
- A generic `CommonMongoRepository<T, ID>`. - 범용 `CommonMongoRepository<T, ID>`.
- Arbitrary runtime `runCommand`. - 실행 중 임의의 `runCommand`.
- Automatic index creation in production. - 운영에서 index 자동 생성.
- A Standalone production contract. - Standalone 운영 계약.
- TTL as an exact business scheduler or as the only access control. - 정확한 업무 일정 도구나 유일한 접근 제어로서의 TTL.
- Publishing raw change events as external business integration events. - 날것의 change event를 외부 업무 통합 이벤트로 내보내기.
- GridFS as the source of truth for new files. - 새 파일의 정본으로서의 GridFS.
- Java fully-qualified class names as a long-lived BSON schema. - 오래 사는 BSON schema로서의 Java FQCN.
- Unbounded skip pagination, unbounded aggregation pipelines, unbounded regex, unbounded results. - 상한 없는 skip 페이지 나누기, 상한 없는 aggregation pipeline, 상한 없는 regex, 상한 없는 결과.
## 7. Capability tiers ## 7. Capability 등급
| Tier | Capabilities | Enablement | | 등급 | Capability | 켜는 법 |
|---|---|---| |---|---|---|
| Stable, auto-configured | Mapping and BSON converters, imperative execution, atomic update, bulk partial results, consistency profiles, retry/translation, operation budgets, observability, typed client profiles, startup validation, health | Beans registered when `app.persistence-mongo.enabled=true`. | | Stable, 자동 구성 | 매핑과 BSON converter, 명령형 실행, atomic update, bulk 부분 결과, 일관성 profile, 재시도/변환, 연산 예산, 관측, 타입 있는 client profile, 시작 검증, health | `app.persistence-mongo.enabled=true`일 때 bean을 등록한다. |
| Stable, library API | Transactions, causal sessions, optimistic revision, query builder and keyset pagination, aggregation executor, schema/index/validator manifests and diffs, TTL contract, GeoJSON, migration runner, admin plane, native capability gateway | The adopter's adapter leaf takes this leaf as `implementation` and constructs the type. | | Stable, 라이브러리 API | transaction, causal session, 낙관적 revision, query builder와 keyset 페이지 나누기, aggregation executor, schema/index/validator manifest와 diff, TTL 계약, GeoJSON, migration runner, admin plane, native capability gateway | 도입하는 쪽의 어댑터 leaf가 이 leaf를 `implementation`으로 받고 타입을 만든다. |
| Advanced, library API | Sharding-aware query and shard admin, CSFLE, Queryable Encryption (equality/range), shared-collection tenancy policies | Same, plus a `MongoAdvancedCapabilityGuard` whose flags enable the capability. No configuration property. | | Advanced, 라이브러리 API | shard를 아는 query와 shard admin, CSFLE, Queryable Encryption(equality/range), shared collection tenancy 정책 | 위와 같고, 그 capability를 켠 flag의 `MongoAdvancedCapabilityGuard`가 더 필요하다. 설정 속성은 없다. |
| Experimental, library API | Database-per-tenant client registry and migration coordinator, reshard approval | Same as Advanced; promotion additionally requires the evidence in [ADR-MONGO-ADV-001](../adr/ADR-MONGO-ADV-001-capability-promotion.md). | | Experimental, 라이브러리 API | tenant마다 database client registry와 migration coordinator, reshard 승인 | Advanced와 같다. 승격에는 [ADR-MONGO-ADV-001](../adr/ADR-MONGO-ADV-001-capability-promotion.md)의 증거가 더 필요하다. |
Search, vector search, time series and GridFS compatibility were interfaces with no implementation 검색, vector 검색, time series, GridFS 호환은 구현 없는 interface였고 2026-09-25에 지웠다
and were removed on 2026-09-25 (`docs/capability-status.md`). (`docs/capability-status.md`).
@@ -1,36 +0,0 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-08-14
- 요약: 알림 submit()은 영속적으로 받아들였다는 뜻이라는 결정이다.
- 현재 정본: `docs/notification/support-matrix.md`
<!-- 머리 블록 끝 -->
# NOTIF-ADR-001 — `submit()` means durable acceptance
## Status
Accepted.
## Context
The obvious API for a notification platform is `send()` returning success or failure. Every channel
this platform supports makes that return value a lie:
- SES accepts a request, returns a `MessageId`, and can still decline to send.
- Twilio separates `accepted`, `sent` and `delivered` into distinct, later events.
- APNs accepts a notification and may then deliver, store or discard it.
- Web Push separates push-service acceptance from user-agent acknowledgement at the protocol level.
## Decision
`submit()` and `schedule()` return once the logical request and its recipient jobs are committed to
the database. The receipt carries `notificationId`, `RequestStatus` and `acceptedAt`, and has no
`delivered`, `sent` or `read` component. No provider is contacted while the transaction is open.
## Consequences
Callers cannot mistake acceptance for delivery, because the type does not offer that reading.
Delivery state is a separate query against the projection built from the provider event ledger. The
cost is that "did it arrive?" is a second question — which is the honest number of questions.
@@ -1,34 +0,0 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-08-14
- 요약: 알림 상태를 덧붙이기만 하는 이벤트 원장과 채널별 projector로 둔다는 결정이다.
- 현재 정본: `docs/notification/support-matrix.md`
<!-- 머리 블록 끝 -->
# NOTIF-ADR-002 — append-only event ledger with channel projectors
## Status
Accepted.
## Context
A single linear delivery status has to be updated in place, which forces a rule for deciding whether
a new event outranks the stored one. The natural rule — compare ordinals — is wrong for real provider
traffic. Twilio does not guarantee callback ordering, so `sent` arrives after `delivered`. Email
generates complaints after deliveries. Both cases lose information under an ordinal rule.
## Decision
Provider events are appended to an immutable ledger before any projection runs. Channel-specific
projectors merge events into `SubmissionOutcome`, `DeliveryOutcome`, `EvidenceLevel`,
`EngagementFacts` and `SuppressionFacts` using explicit transition tables. Projection is idempotent
and can be replayed from the ledger.
## Consequences
Duplicate, out-of-order and late events are normal inputs rather than defects. A projector bug is
recoverable, because the events it mis-projected are still stored. Projector versions can be migrated
by replay. The cost is a second write per event and a projection that can lag its ledger.
@@ -1,46 +0,0 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-08-14
- 요약: 결과가 모호한 제출을 정식 상태로 둔다는 결정이다.
- 현재 정본: `docs/notification/support-matrix.md`
<!-- 머리 블록 끝 -->
# NOTIF-ADR-003 — ambiguous submission is a first-class state
## Status
Accepted.
## Context
The most common serious failure is not a rejection. It is a request whose body reached the provider
and whose response never came back. The platform has no provider request id, and the user may or may
not have received the notification.
Treating that as a failure produces duplicates: a retry sends a second message, and a cross-channel
fallback sends the SMS next to the push that already arrived. Treating it as a success loses real
failures.
## Decision
`AMBIGUOUS` is a stored `SubmissionOutcome` and `AttemptConfirmation`. Attempts record
`requestStarted`, `requestBodyCommitted` and `providerResponseReceived`, each with an
`EvidenceCertainty` of `PROVEN`, `INFERRED` or `UNKNOWN`, so an adapter that does not know is not
forced to answer `false`.
While an ambiguous attempt exists on a recipient delivery:
- automatic retry is blocked unless the provider proves per-request idempotency
- automatic cross-channel fallback is blocked unconditionally
- reconciliation runs where the provider supports a status query
- otherwise the delivery stops and waits for an operator
Operator redrive of an ambiguous attempt requires explicit duplicate-risk approval.
## Consequences
Some notifications stop in a state that needs a human or a reconciliation pass. That is the intended
trade: an unresolved unknown is cheaper than a guaranteed duplicate, and the state is visible rather
than silently resolved in either direction.
@@ -1,36 +0,0 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-08-14
- 요약: FCM 대상은 installation id를 먼저 쓴다는 결정이다.
- 현재 정본: `docs/notification/provider-runbooks.md`
<!-- 머리 블록 끝 -->
# NOTIF-ADR-004 — FCM installation id is the primary target
## Status
Accepted.
## Context
Firebase now recommends the installation id (FID) and treats registration-token multicast paths as
legacy. A contact point model built on a single `token` string would encode the older model as the
only one, and a later migration would be a runtime interpretation problem: the same string field
would mean different things for different rows.
## Decision
`MobilePushTarget` is a sealed hierarchy of `FcmInstallationId`, `LegacyFcmRegistrationToken` and
`ApnsDeviceToken`. The kinds are separate types, never a discriminator on one string field, and each
carries its own `ContactPointType` so the uniqueness scope and the encryption associated data differ.
APNs tokens additionally carry their environment, because sandbox and production are separate
namespaces rather than a flag.
## Consequences
Migrating a target kind is a compile-time change with an exhaustive `switch`, not a runtime guess.
The adapter maps each kind to its own wire representation, so a provider changing one path cannot
silently change the other. The cost is one more type than a string field would need.
+77 -87
View File
@@ -1,77 +1,53 @@
# Notification payload at rest — threat model and decision (NTF-INT-007) # 저장된 알림 payload — 위협 모델과 결정 (NTF-INT-007)
Wave 2 Task D6 offers two branches and requires that one be chosen and implemented fully: 결론: 템플릿 변수(payload)는 저장소 경계에서 암호화한다(branch (a)). 변수를 「민감하지 않은 값」으로 제한하는 길
(branch (b))은 쓸 수 없다. 변수가 곧 메시지의 내용이기 때문이다.
- **(a) encryption** — a codec/port, ciphertext envelope, key id, rotation and history, row migration, Wave 2 Task D6은 두 길을 주고, 하나를 골라 끝까지 구현하라고 요구했다.
and a decryption-failure contract;
- **(b) restriction** — this document plus a static restriction proving the variable types cannot
carry sensitive values.
The plan recommends (b) **"if and only if the variable types can genuinely be restricted to - **(a) 암호화** — codec·port, 암호문 envelope, key id, 교체와 이력, 행 마이그레이션, 복호화 실패 계약.
non-sensitive values"**. They cannot. This document records why, what that leaves, and when the - **(b) 제한** — 이 문서, 그리고 변수 타입이 민감한 값을 담을 수 없음을 보이는 정적 제한.
remaining branch lands.
## What is stored, and where 계획은 **「변수 타입을 정말로 민감하지 않은 값으로 제한할 수 있을 때만」** (b)를 권했다. 제한할 수 없다. 이 문서는
그 이유와, 그래서 고른 (a)가 지금 어떻게 들어가 있는지를 적는다.
`CanonicalNotificationPlanWriter.request(...)` puts `encoded.variablesPayload()` into ## 지금 상태
`NotificationRequestRecord` verbatim. `JpaNotificationRequestStore` writes that record to
`notification_request.variables_payload` with no transformation. There is no encryption anywhere on
this path.
## Why the restriction branch is unavailable - `NotificationPayloadProtection`이 애플리케이션이 가진 port이고, `AesGcmNotificationPayloadProtection`이 AES-GCM
구현이다.
- `NotificationRecordMapper`가 그것을 **필수** 생성자 인자로 받아 적용한다. 그래서 payload를 평문으로 둔 채 알림
저장소를 조립할 수 없다.
- 쓰기 경로는 조립에서 닿는다. `NotificationJpaPersistenceFacade`는 persistence-notification leaf의
`AutoConfiguration.imports`가 올린다.
- 평문 행이 이미 있는 배포는 마이그레이션에서 멈춘다. `V10__variables_payload_envelope_guard.sql`은 행을 다시
암호화하지 않고, 보호되지 않은 행이 있으면 실패한다.
- `NotificationPayloadAtRestContractTest`가 이 문서가 기대는 사실을 모두 단언한다. 하나라도 거짓이 되면 그 테스트가
실패하므로, 결정이 저절로 낡지 않는다.
- 알림은 Stable이 아니다(`docs/notification/support-matrix.md`).
Template variables are a closed algebra — `NotificationVariable` permits `TextValue`, `NumberValue`, ## 무엇이 어디에 저장되나
`BooleanValue`, `NullValue`, `ListValue`, `ObjectValue` — which is a real improvement over the
`Map<String, Object>` it replaced. But `TextValue` holds an arbitrary UTF-8 string of up to 8 KiB,
and that is not an oversight to be tightened: **the variables are the recipient-specific content of
the message**. A password-reset code, an order total, a delivery address, a patient's appointment
time — those are what a notification is for.
A restriction to "non-sensitive values" would therefore be one of two things, and both are worse `CanonicalNotificationPlanWriter.request(...)`는 `encoded.variablesPayload()`를 그대로 `NotificationRequestRecord`에
than the problem: 넣는다. 애플리케이션은 그것을 렌더링해야 하므로 여기서는 평문이 맞다. 「저장된(at rest)」은 행 안을 뜻하므로
envelope는 여기가 아니라 저장소 경계에서 씌운다. `notification_request.variables_payload`에는 base64 AES-GCM
envelope가 들어간다.
- **unenforceable** — a comment saying callers should not put sensitive data in a field designed to ## 제한 가지를 쓸 수 없는 이유
carry the message's content, which is a policy no type checks and no reviewer can see violated;
- **enforced and useless** — a type that refuses free text, which does not restrict the capability so
much as delete it.
The precondition on the plan's recommendation is false. Branch (b) is not available. 템플릿 변수는 닫힌 대수다. `NotificationVariable`은 `TextValue`, `NumberValue`, `BooleanValue`, `NullValue`,
`ListValue`, `ObjectValue`만 허용한다. 이것이 대신한 `Map<String, Object>`보다 확실히 낫다. 그러나 `TextValue`는 8 KiB까지의
아무 UTF-8 문자열을 담고, 그것은 조여야 할 실수가 아니다. **변수는 메시지의 수신자별 내용이다.** 비밀번호 재설정
코드, 주문 합계, 배송 주소, 환자의 예약 시각, 알림은 그것을 보내려고 있다.
> **Status: branch (a) implemented at the storage boundary.** `NotificationPayloadProtection` is the 그래서 「민감하지 않은 값」으로의 제한은 둘 중 하나가 되고, 둘 다 문제보다 나쁘다.
> application-owned port, `AesGcmNotificationPayloadProtection` the AES-GCM implementation, and
> `NotificationRecordMapper` applies it — as a **required** constructor argument, so a composition
> cannot assemble the notification stores while leaving the payload in plaintext. What remains before
> the facade can be imported is the row migration for any deployment that already has plaintext rows,
> and the `local-notification-*` lanes. The analysis below is kept as written, because it is what the
> decision rests on.
## Decision: branch (a), landing with the persistence wiring - **강제할 수 없음** — 메시지 내용을 담으려고 만든 칸에 민감한 데이터를 넣지 말라는 주석. 어떤 타입도 확인하지
않고, 어떤 리뷰어도 위반을 볼 수 없는 정책이다.
- **강제하지만 쓸모없음** — 자유 텍스트를 거부하는 타입. capability를 제한한다기보다 지운다.
Encryption is therefore the required branch. Its scope is unchanged from the plan: a codec behind an 계획의 권고에 붙은 전제가 거짓이다. (b)는 쓸 수 없다.
application port, a ciphertext envelope carrying its key id, key rotation with history so an old row
stays readable, a migration for existing rows, and an explicit contract for what a decryption failure
does to a request.
**It lands in the change unit that makes the write path reachable, and not before.** The reason is a ## envelope와 key id를 두는 이유
fact the spec did not have: `NotificationJpaPersistenceFacade`, which assembles
`JpaNotificationRequestStore`, is imported by nothing. The composition root's component scan excludes
the persistence package by design, and no configuration imports the facade — so the notification
capability has **no JPA persistence at all**, and no deployment currently writes this payload
anywhere. The defect is real in the code and latent in the runtime.
Designing key rotation and a row migration for rows that no deployment produces would be building the
migration before the table. Worse, it would settle the envelope's shape before the store that has to
read it is wired, which is the order that produces an envelope the store cannot use.
**One correction, learned by trying it.** This section said the envelope "lands with the wiring".
Wiring the facade first — to register the SMTP assembler — made
`NotificationPayloadAtRestContractTest` fail on the case asserting the write path is reachable from
no composition, which is exactly what that case is for. The wave forbids connecting wiring over a
known security finding on a runtime path, so the wiring was reverted and the envelope built first.
The honest ordering is **envelope before or with the wiring, never after**, and the contract test now
enforces it by failing on the wiring alone.
### The envelope, and why it has a key id
``` ```
byte version always 1 byte version always 1
@@ -81,36 +57,50 @@ byte[12] nonce
byte[] ciphertext + GCM tag byte[] ciphertext + GCM tag
``` ```
The key id is the reason there is a format at all. This repository's callback protection stores nonce 형식을 두는 이유는 key id다. 이 저장소의 콜백 보호는 한때 nonce와 암호문만 저장했다. 그러면 활성 키가 바뀌는 날
and ciphertext and nothing else, so the day the active key changes, every row written under the 앞 키로 쓴 행은 모두 읽을 수 없게 되고, 행 안의 어떤 것도 어느 키가 필요했는지 말하지 못한다. 틈 있는 교체가 아니라
previous one becomes unreadable and nothing in the row can say which key it needed — that is not a 교체가 없는 것이다. `SecretMaterialProvider`가 이미 `keyById`를 드러내므로, id를 다시 읽어 바로 그 키를 달라고 하면
rotation story with a gap in it, it is the absence of one. `SecretMaterialProvider` already exposes 교체는 데이터 마이그레이션이 아니라 기본값 변경이 된다. version 바이트는 1바이트이고, 형식을 바꿀 수 있게 해 준다.
`keyById`, so reading the id back and asking for that specific key makes rotation a change of default
rather than a data migration. The version byte costs one byte and is what allows the format to change
at all.
The header is passed as **AAD**, not merely prefixed: without that, the key id is attacker-editable header는 앞에 붙이기만 하는 것이 아니라 **AAD**로 넘긴다. 그러지 않으면 공격자가 key id를 고쳐 envelope를 자기가
and an envelope could be redirected at a key of the attacker's choosing. 고른 키로 돌릴 수 있다.
A failed decryption throws `NotificationPayloadUnreadableException` rather than returning empty. A 복호화에 실패하면 빈 값을 돌려주지 않고 `NotificationPayloadUnreadableException`을 던진다. 빈 payload를 받은
caller handed an empty payload renders every variable as nothing and sends "Hello , your code is " to 호출자는 모든 변수를 빈 값으로 렌더링해 실제 사람에게 "Hello , your code is "를 보낸다. 실패를 보고하는 대신 실패를
a real person — the failure delivered instead of reported. All three causes (unknown key, wrong key, 배달하는 것이다. 세 원인(모르는 키, 틀린 키, 고쳐진 암호문)은 한 메시지로 합친다. 셋을 구별해 주면 공격자에게 셋 중
modified ciphertext) collapse into one message, because telling them apart tells an attacker which of 무엇을 해냈는지 알려 주기 때문이다.
the three they achieved.
## What must not be done instead ## 키 교체 순서
**Requiring `PAYLOAD_ENCRYPTION` in `INGEST_ONLY` is not a fix.** That secret is consumed by exactly 설정 키는 `app.notification.platform.secrets` 아래에 있다(`notification.yml`).
one thing — `AesGcmCallbackPayloadProtection`, which protects raw callback bodies — and by nothing on
the accept path. Demanding it would make a deployment supply a key that protects nothing while the
payload it appears to be about stays in plaintext. The repository already has one defect of that
exact shape: `app.graphql.cursor.key-ids` (key removed 2026-09-25), which production refuses to start without and which no
code signs a cursor with (GQL-INT-003). Adding a second would make the pattern a habit.
## Consequence 1. 새 키 값과 새 key id를 같은 배포에서 바꾼다(예: `APP_NOTIFICATION_PLATFORM_PAYLOAD_ENCRYPTION_KEY`와
`APP_NOTIFICATION_PLATFORM_PAYLOAD_ENCRYPTION_KEY_ID`). 고정된 id는 교체를 앞 키와 구별할 수 없게 한다.
2. 같은 배포에서 밀려난 키 값을 `historical-keys.<목적>.<옛 id>` 아래에 둔다(예:
`historical-keys.PAYLOAD_ENCRYPTION.payload-2026-01`). 목적은 id에서 알아낼 수 없고, id로 키를 푸는 쪽은 목적이 다른
키를 거부한다. 그러니 다른 목적 아래 둔 옛 키는 풀리기는 해도 거부된다.
3. 옛 키로 쓴 행이 남아 있는 동안 옛 키를 그대로 둔다. `SettingsSecretMaterialProvider.keyById`는 모르는 id를 현재
키로 대신하지 않고 거부한다. 대신하면 이력의 모든 행이 읽을 때 인증 tag 실패가 된다.
Notification is **not promoted to Stable**, per the index's scope boundaries, until branch (a) is ## 결정의 이력
complete. The three notification Compose lanes stay non-blocking. `NotificationPayloadAtRestContractTest`
holds every fact this decision rests on, so the decision expires automatically if any of them stops > 이력: 결정 당시(Wave 2) `NotificationJpaPersistenceFacade`는 아무도 import하지 않았다. 조립 루트의 component scan은
being true — in particular, the assertion that no encryption sits on the accept path fails the moment > 설계상 persistence 패키지를 빼고, 어떤 설정도 facade를 import하지 않아서, 알림 capability에는 JPA 영속성이 아예 없었다.
somebody adds one, which is the change this document is waiting for. > 결함은 코드에는 있고 런타임에는 숨어 있었다. 그래서 처음에는 「envelope는 그 wiring과 함께 들어간다」고 정했다.
> 아무 배포도 만들지 않는 행을 위해 키 교체와 행 마이그레이션을 설계하는 것은 테이블보다 마이그레이션을 먼저 짓는
> 일이었다.
>
> 해 보고 배운 정정이 하나 있다. SMTP assembler를 등록하려고 facade를 먼저 wiring하자,
> `NotificationPayloadAtRestContractTest`의 「쓰기 경로가 어느 조립에서도 닿지 않는다」 단언이 실패했다. 그 단언은 바로
> 그것을 잡으려고 있었다. Wave는 런타임 경로에 알려진 보안 발견을 둔 채 wiring을 잇는 것을 막았으므로 wiring을 되돌리고
> envelope를 먼저 지었다. 맞는 순서는 **envelope를 wiring 전이나 함께, 뒤에는 절대 아니다**이다.
>
> 결정 당시 `PAYLOAD_ENCRYPTION` secret을 쓰는 곳은 원본 콜백 본문을 보호하는 `AesGcmCallbackPayloadProtection` 하나뿐이었고
> 받기 경로에는 없었다. 그래서 `INGEST_ONLY`에서 그것을 요구하는 것은 고침이 아니었다. 아무것도 보호하지 않는 키를
> 배포에 요구하고, 그것이 다룬다고 보이는 payload는 평문으로 남는다. 저장소에는 이미 그런 꼴의 결함이 하나 있었다.
> `app.graphql.cursor.key-ids`(2026-09-25에 키를 지움)는 운영이 그것 없이는 뜨지 않으면서, 어떤 코드도 그것으로 cursor에
> 서명하지 않았다(GQL-INT-003). 지금은 `AesGcmNotificationPayloadProtection` 하나가 같은 envelope로 받은 payload와 보관하는
> 콜백을 모두 덮고, `NotificationSecretRequirements`가 이 목적을 모든 설정에서 요구한다.
>
> 결정 당시 결론은 이랬다. 알림은 색인의 범위 경계에 따라 (a)가 끝날 때까지 Stable로 올리지 않는다. 알림 Compose
> lane 셋은 막지 않는 lane으로 둔다.
+27 -28
View File
@@ -1,6 +1,6 @@
# Callbacks and reconciliation # 콜백과 맞추기(reconciliation)
## Ingestion order ## 받는 순서
```text ```text
body size limit body size limit
@@ -16,41 +16,40 @@ body size limit
→ 2xx → 2xx
``` ```
Appending before projecting is what makes a fast 2xx honest. The provider is told the event is projection보다 ledger 추가를 먼저 하기 때문에 빠른 2xx가 정직하다. provider에게는 이벤트가 기록됐다고 알리고,
recorded, and a projector defect becomes a replay problem rather than a lost event. projector 결함은 이벤트 유실이 아니라 replay 문제가 된다.
A rejected signature is recorded in the security audit, never in the provider event ledger. Writing 서명이 거부된 콜백은 provider event ledger가 아니라 보안 감사에 기록한다. ledger에 쓰면 엔드포인트에 닿는 누구나
it to the ledger would let anyone who can reach the endpoint fill a delivery history with noise. 전달 이력을 잡음으로 채울 수 있다.
## Duplicates and ordering ## 중복과 순서
Duplicate suppression uses `(providerProfileId, providerEventId)` where the provider supplies an 중복 억제는 provider가 event id를 주면 `(providerProfileId, providerEventId)`를 쓰고, 주지 않으면 profile, request id,
event id, and a deterministic fingerprint over profile, request id, event type, occurrence time and event 종류, 발생 시각, payload digest로 만든 결정적 fingerprint를 쓴다. 중복은 확인 응답하고 projection은 정확히 한 번
payload digest where it does not. A duplicate is acknowledged and projected exactly once. 한다.
Out-of-order callbacks are normal. Ordering is resolved by event semantics, not by arrival time. 순서가 뒤바뀐 콜백은 보통이다. 순서는 도착 시각이 아니라 이벤트의 뜻으로 정한다.
## Unknown fields ## 모르는 칸
Callback parsers tolerate unknown JSON fields. Normalization only rejects a payload when a field 콜백 parser는 모르는 JSON 칸을 받아들인다. 정규화는 attempt를 가리키는 데 필요한 칸이 없을 때만 payload를 거부한다.
required to identify the attempt is missing. Providers add fields; that must not stop ingestion. provider는 칸을 더한다. 그것 때문에 받기가 멈추면 안 된다.
## Reconciliation ## 맞추기
Reconciliation targets: 맞추기 대상:
- attempts stuck in `DISPATCHING` past their lease - lease가 지나도 `DISPATCHING`에 멈춘 attempt
- ambiguous submissions - 모호한 제출
- accepted attempts whose callback SLA has expired - 콜백 SLA가 지난, 수락된 attempt
- unmatched provider events - 짝이 없는 provider 이벤트
A confirmed query result is appended to the same ledger with `source = RECONCILIATION` and projected 확인된 조회 결과는 `source = RECONCILIATION`으로 같은 ledger에 추가하고 같은 projector가 projection한다. 그래서
by the same projector, so projection replay stays possible: there is no privileged second path that projection replay가 계속 가능하다. projection을 직접 쓰는 특별한 두 번째 길은 없다.
writes projections directly.
Where a provider has no status-query capability, the platform records `Unsupported` and leaves the provider에 상태 조회 기능이 없으면 플랫폼은 `Unsupported`를 기록하고 attempt를 모호한 채로 둔다. 최종 상태를 짐작하지
attempt ambiguous. It does not infer a final status. 않는다.
The shipped families, SES and SMTP, have no reconciliation: their assemblers contribute no 내보내는 family인 SES와 SMTP는 맞추기가 없다. 그 assembler는 `ReconciliationCapability`를 보태지 않으므로, 둘의 맞추기
`ReconciliationCapability`, so every reconciliation job for them ends `Unsupported`. The slot on 작업은 모두 `Unsupported`로 끝난다. `AssembledProvider`의 그 자리는 도입하는 쪽이 자기 상태 조회와 함께 조립하는 provider
`AssembledProvider` is for a provider family an adopter assembles with a status query of its own. family를 위한 것이다.
+144 -153
View File
@@ -1,211 +1,202 @@
# Configuration reference # 설정 참조
The notification delivery platform binds under `app.notification.platform`. The tree lives in 알림 전달 플랫폼은 `app.notification.platform` 아래에 묶인다. 설정 트리는
`src/composition/notification-platform/src/main/resources/config/module-defaults/notification.yml`, `src/composition/notification-platform/src/main/resources/config/module-defaults/notification.yml`에 있고,
which the support leaf's `ModuleDefaultsEnvironmentPostProcessor` loads at the lowest precedence, support leaf의 `ModuleDefaultsEnvironmentPostProcessor`가 가장 낮은 우선순위로 읽는다. 그래서 이 모듈이 없는
so an application without the module carries none of it. The module is in no default composition: a 애플리케이션에는 이 설정이 하나도 없다. 이 모듈은 어느 기본 조립에도 없다. 서비스가
service selects it with `runtimeOnly project(':composition:notification-platform')` (plus the `app-bootstrap/build.gradle`에 `runtimeOnly project(':composition:notification-platform')`(와 persistence-jpa 줄)를
persistence-jpa line) in `app-bootstrap/build.gradle`, and it is on when present. Every value carries 더해 고르고, 모듈이 있으면 켜진다. 값마다 기본값이 붙어 있으므로 플랫폼을 끄는 배포는 아무것도 주지 않아도 된다.
an inline default, so a deployment that switches the platform off supplies nothing.
Until 2026-08-15 this page named properties the binding did not have — `max-retry-concurrency`, > 이력: 2026-08-15까지 이 문서는 바인딩에 없는 속성(`max-retry-concurrency`, `scheduler-poll-interval`,
`scheduler-poll-interval`, `callback-worker-concurrency` — and omitted three it did. There was no > `callback-worker-concurrency`)을 적었고, 있는 속성 셋을 빠뜨렸다. `application.yml`에 트리가 아예 없어서, 플랫폼을
tree in `application.yml` at all, so the only way to configure the platform was to guess environment > 설정하려면 Boot의 relaxed binding으로 환경 변수 이름을 짐작해야 했다.
variable names from Boot's relaxed binding. `NotificationEnvironmentRegistryTest`
(`:composition:notification-platform:test`) now fails when the shipped YAML and
`docs/registries/env-keys.yaml` disagree.
## Master switch 지금은 내보내는 YAML과 `docs/registries/env-keys.yaml`이 다르면 `NotificationEnvironmentRegistryTest`
(`:composition:notification-platform:test`)가 실패한다.
| Property | Environment variable | Default | Meaning | ## 주 스위치
| 속성 | 환경 변수 | 기본값 | 뜻 |
|---|---|---|---| |---|---|---|---|
| `enabled` | `APP_NOTIFICATION_PLATFORM_ENABLED` | `true` | On while the module is present. `false` binds nothing at all: no runtime, no schema check, no scheduler thread, no secret required | | `enabled` | `APP_NOTIFICATION_PLATFORM_ENABLED` | `true` | 모듈이 있으면 켜진다. `false`면 아무것도 묶지 않는다. 런타임도, 스키마 검사도, scheduler 스레드도, 필요한 secret도 없다 |
| `mode` | `APP_NOTIFICATION_PLATFORM_MODE` | `SERVING` | `SERVING` refuses to start without a working provider; `INGEST_ONLY` stores requests and does not dispatch: it builds no provider runtime but records each enabled profile's route, so a request accepted now is delivered later on that route by a `SERVING` deployment (handoff) | | `mode` | `APP_NOTIFICATION_PLATFORM_MODE` | `SERVING` | `SERVING`은 동작하는 provider가 없으면 뜨기를 거부한다. `INGEST_ONLY`는 요청을 저장만 하고 보내지 않는다. provider 런타임을 만들지 않지만 켜진 profile마다 route를 기록하므로, 지금 받은 요청은 나중에 `SERVING` 배포가 그 route로 보낸다(handoff) |
## Dispatch ## 발송
| Property | Environment variable | Default | Bound | | 속성 | 환경 변수 | 기본값 | 범위 |
|---|---|---|---| |---|---|---|---|
| `dispatch.claim-batch-size` | `APP_NOTIFICATION_PLATFORM_CLAIM_BATCH_SIZE` | `50` | 1..1000 | | `dispatch.claim-batch-size` | `APP_NOTIFICATION_PLATFORM_CLAIM_BATCH_SIZE` | `50` | 1..1000 |
| `dispatch.lease-duration` | `APP_NOTIFICATION_PLATFORM_LEASE_DURATION` | `2m` | positive, finite | | `dispatch.lease-duration` | `APP_NOTIFICATION_PLATFORM_LEASE_DURATION` | `2m` | 양수, 유한 |
| `dispatch.poll-interval` | `APP_NOTIFICATION_PLATFORM_POLL_INTERVAL` | `1s` | positive, finite | | `dispatch.poll-interval` | `APP_NOTIFICATION_PLATFORM_POLL_INTERVAL` | `1s` | 양수, 유한 |
| `dispatch.max-global-concurrency` | `APP_NOTIFICATION_PLATFORM_MAX_CONCURRENCY` | `64` | positive | | `dispatch.max-global-concurrency` | `APP_NOTIFICATION_PLATFORM_MAX_CONCURRENCY` | `64` | 양수 |
| `dispatch.max-additional-attempts` | `APP_NOTIFICATION_PLATFORM_MAX_ADDITIONAL_ATTEMPTS` | `4` | non-negative | | `dispatch.max-additional-attempts` | `APP_NOTIFICATION_PLATFORM_MAX_ADDITIONAL_ATTEMPTS` | `4` | 0 이상 |
| `dispatch.max-queue-age` | `APP_NOTIFICATION_PLATFORM_MAX_QUEUE_AGE` | `24h` | positive | | `dispatch.max-queue-age` | `APP_NOTIFICATION_PLATFORM_MAX_QUEUE_AGE` | `24h` | 양수 |
| `dispatch.allow-ambiguous-fallback` | `APP_NOTIFICATION_PLATFORM_ALLOW_AMBIGUOUS_FALLBACK` | `false` | boolean | | `dispatch.allow-ambiguous-fallback` | `APP_NOTIFICATION_PLATFORM_ALLOW_AMBIGUOUS_FALLBACK` | `false` | boolean |
Every value is bounded. "Unlimited" is not an accepted configuration. 모든 값에 상한이 있다. 「무제한」은 받는 설정이 아니다.
The lease must outlast a provider call plus its timeout. Below that, a delivery a live worker is lease는 provider 호출과 그 시간 상한보다 길어야 한다. 그보다 짧으면, 살아 있는 worker가 아직 기다리는 전달을 두 번째
still waiting on gets claimed by a second worker, and the recipient receives the notification twice. worker가 claim하고, 수신자는 알림을 두 번 받는다.
## Callbacks ## 콜백
| Property | Environment variable | Default | Bound | | 속성 | 환경 변수 | 기본값 | 범위 |
|---|---|---|---| |---|---|---|---|
| `callbacks.enabled` | `APP_NOTIFICATION_PLATFORM_CALLBACKS_ENABLED` | `false` | boolean | | `callbacks.enabled` | `APP_NOTIFICATION_PLATFORM_CALLBACKS_ENABLED` | `false` | boolean |
| `callbacks.max-body-bytes` | `APP_NOTIFICATION_PLATFORM_CALLBACK_MAX_BODY_BYTES` | `65251` | 1..65251 | | `callbacks.max-body-bytes` | `APP_NOTIFICATION_PLATFORM_CALLBACK_MAX_BODY_BYTES` | `65251` | 1..65251 |
| `callbacks.replay-skew` | `APP_NOTIFICATION_PLATFORM_CALLBACK_REPLAY_SKEW` | `1h` | positive; SNS messages whose `Timestamp` is further than this from receipt, either way, are rejected. The default is SNS's longest HTTP/S retry period (3,600 s), so a bounce or complaint SNS redelivers after an outage is still accepted; a replay inside the window is a duplicate in the provider event ledger, not a second event (review 05-20) | | `callbacks.replay-skew` | `APP_NOTIFICATION_PLATFORM_CALLBACK_REPLAY_SKEW` | `1h` | 양수. `Timestamp`가 받은 시각에서 이보다 멀리(앞이든 뒤든) 떨어진 SNS 메시지는 거절한다. 기본값은 SNS의 HTTP/S 재시도 기간 중 가장 긴 값(3,600 s)이라, 장애 뒤에 SNS가 다시 보내는 bounce·complaint도 받는다. 창 안의 replay는 provider event ledger에서 중복이지 두 번째 이벤트가 아니다(review 05-20) |
| `callbacks.trusted-proxies` | `APP_NOTIFICATION_PLATFORM_CALLBACK_TRUSTED_PROXIES` | *(empty)* | CSV of peer addresses |
콜백 응답: 기록(중복 포함) `204`, 거절 `400`(서명·topic·시각·형식), 본문 초과 `413`. SNS 서명 인증서를 가져오지 못하면(5xx·408·429·네트워크 실패) 거절하지 않고 `503`+`Retry-After`로 답한다 — SNS는 4xx를 처리 완료로 보고 재전송을 멈추지만 5xx는 다시 보낸다(review 05-20). 인증서 URL이 그 밖의 4xx(403·404 등)로 답하면 SNS가 발급하지 않은 인증서를 가리킨 위조 콜백이므로 서명 검증 실패로 `400` 거절하고 보안 감사(`callbackSignatureRejected`)에 남긴다(review 2026-11-03 RR-07-03). 호스트 검사를 통과한 URL이라 답하는 쪽은 SNS다. 콜백 응답: 기록(중복 포함) `204`, 거절 `400`(서명·topic·시각·형식), 본문 초과 `413`. SNS 서명 인증서를 가져오지
못하면(5xx·408·429·네트워크 실패) 거절하지 않고 `503`+`Retry-After`로 답한다. SNS는 4xx를 처리 완료로 보고 재전송을
멈추지만 5xx는 다시 보낸다(review 05-20). 인증서 URL이 그 밖의 4xx(403·404 등)로 답하면 SNS가 발급하지 않은 인증서를
가리킨 위조 콜백이므로 서명 검증 실패로 `400` 거절하고 보안 감사(`callbackSignatureRejected`)에 남긴다(review
2026-11-03 RR-07-03). 호스트 검사를 통과한 URL이라 답하는 쪽은 SNS다.
여러 provider가 요청 URL에 서명하므로, 그 URL을 잘못 재구성하면 정상 webhook이 전부 서명 실패가 된다. 여러 provider가 요청 URL에 서명하므로, 그 URL을 잘못 재구성하면 정상 webhook이 전부 서명 실패가 된다. provider가
`trusted-proxies`가 비어 있으면 forwarded 헤더를 **믿지 않고** 컨테이너가 관측한 값을 쓴다. 무조건 믿으면 서명한 URL은 컨테이너가 보고한 값으로 다시 만든다. 콜백 전용 proxy 목록은 없다. 로드밸런서 뒤에 있는 배포는
아무 호출자나 자기 서명이 검증될 URL을 고를 수 있어 서명 자체가 무의미해진다. 로드밸런서 뒤에 있는 배포는 `APP_SERVER_FORWARD_HEADERS_STRATEGY=native`로 두고 그 proxy를 `server.tomcat.remoteip.internal-proxies`에 적는다.
그 peer를 명시한다. forwarded 헤더를 무조건 믿으면 아무 호출자나 자기 서명이 검증될 URL을 고를 수 있어 서명 자체가 무의미해진다.
65251 is not a round number by accident: it is the ciphertext column's 65536 bytes minus the largest 65251은 우연히 고른 수가 아니다. 암호문 칸의 65536바이트에서 protector가 쓰는 가장 큰 envelope를 뺀 값이다. version
envelope the protector writes — a version byte, a key-id length byte, a key id of up to 255 bytes, the 바이트, key id 길이 바이트, 255바이트까지의 key id, AES-GCM nonce와 tag다. 이보다 큰 값은 설정을 묶을 때 거부되므로
AES-GCM nonce and tag. A larger configured value is refused when the settings bind, so the capability capability가 뜨지 않는다. 그 검사가 생기기 전에는 DB 위의 모든 층을 통과한 뒤, 콜백을 provider에 이미 확인 응답한 다음
does not start; before that check existed it passed every layer above the database and failed the `CHECK` 제약에서 실패했다.
`CHECK` constraint after the callback had already been acknowledged to the provider. The shipped
default was 65508 (nonce and tag only) for a while after the envelope gained its key id, and every
deployment that turned the platform on failed to start until it was corrected (review 2026-11-01
r3-i, found by booting the compose lanes).
## Provider profiles > 이력: envelope에 key id가 붙은 뒤에도 한동안 내보낸 기본값이 65508(nonce와 tag만 뺀 값)이었고, 플랫폼을 켠 배포는 그
> 값을 고칠 때까지 모두 뜨지 못했다(review 2026-11-01 r3-i, compose lane을 띄워서 찾음).
Profiles are a map under `providers`, keyed by profile id. Arbitrary deployment-chosen ids can be ## provider profile
supplied as YAML or through Spring relaxed binding (`APP_NOTIFICATION_PLATFORM_PROVIDERS_<ID>_<FIELD>`).
The shipped reference profiles `smtp` and `ses` additionally expose explicit `APP_NOTIFICATION_PLATFORM_SMTP_*`
and `APP_NOTIFICATION_PLATFORM_SES_*` aliases so operators do not have to invent binding names.
| Field | Meaning | profile은 `providers` 아래의 map이고, 키는 profile id다. 배포가 정한 아무 id나 YAML이나 Spring relaxed binding
(`APP_NOTIFICATION_PLATFORM_PROVIDERS_<ID>_<FIELD>`)으로 줄 수 있다. 내보내는 참조 profile `smtp`와 `ses`는 그 밖에
`APP_NOTIFICATION_PLATFORM_SMTP_*`와 `APP_NOTIFICATION_PLATFORM_SES_*` 별칭도 드러내므로, 운영자가 바인딩 이름을
지어낼 필요가 없다.
| 칸 | 뜻 |
|---|---| |---|---|
| `type` | `SES`, `SMTP` — a closed enum, so an unknown value fails binding rather than assembling into nothing | | `type` | `SES`, `SMTP`. 닫힌 enum이라 모르는 값은 아무것도 조립하지 않고 넘어가는 대신 바인딩에서 실패한다 |
| `enabled` | A disabled profile is bound and validated but contributes no runtime | | `enabled` | 꺼진 profile도 묶이고 검증되지만 런타임에 아무것도 보태지 않는다 |
| `primary-for-channel` | Exactly one primary per channel | | `primary-for-channel` | 채널마다 primary는 정확히 하나 |
| `environment` | Required when enabled | | `environment` | 켜면 필요하다 |
| `credential-profile` | Provider credential key id resolved through `SecretMaterialProvider`; never inline secret material | | `credential-profile` | `SecretMaterialProvider`로 푸는 provider 자격 증명 key id. secret 값을 직접 적지 않는다 |
| `timeout` | Positive and finite | | `timeout` | 양수, 유한 |
| `max-concurrency` | Positive | | `max-concurrency` | 양수 |
| `rate-per-second` | Positive | | `rate-per-second` | 양수 |
A profile pins provider type, environment, credential profile, timeouts, concurrency and rate limit. profile 하나가 provider 종류, 환경, 자격 증명 profile, 시간 상한, 동시성, 속도 제한을 고정한다. 보내는 쪽 신원과 자격
Sender identity and credential profile are separate concerns. 증명 profile은 서로 다른 문제다.
### SES profile fields ### SES profile 칸
An enabled SES profile adds a typed `ses` block: 켜진 SES profile에는 타입이 있는 `ses` 블록이 더해진다.
| Field | Meaning | | 칸 | 뜻 |
|---|---| |---|---|
| `ses.endpoint` | SES API base URI, used as the AWS SDK client's endpoint override | | `ses.endpoint` | SES API 기본 URI. AWS SDK 클라이언트의 endpoint override로 쓴다 |
| `ses.region` | AWS region the SDK signs for | | `ses.region` | SDK가 서명하는 AWS region |
| `ses.sender-identity` | verified SES From identity | | `ses.sender-identity` | 검증된 SES From 신원 |
| `ses.access-key-id` | AWS access key id; identifier only, not secret material | | `ses.access-key-id` | AWS access key id. 식별자일 뿐 secret 값이 아니다 |
| `ses.configuration-set` | optional SES configuration-set name | | `ses.configuration-set` | 선택. SES configuration-set 이름 |
| `ses.allowed-topic-arns` | SNS topic ARNs whose SES events this profile accepts (`APP_NOTIFICATION_PLATFORM_SES_ALLOWED_TOPIC_ARNS`, comma-separated). Required when `callbacks.enabled=true`: binding fails without it, because a valid SNS signature only proves AWS sent the message and anyone can own a topic | | `ses.allowed-topic-arns` | 이 profile이 SES 이벤트를 받는 SNS topic ARN(`APP_NOTIFICATION_PLATFORM_SES_ALLOWED_TOPIC_ARNS`, 쉼표로 구분). `callbacks.enabled=true`면 필요하다. 없으면 바인딩이 실패한다. 유효한 SNS 서명은 AWS가 메시지를 보냈다는 것만 증명하고, topic은 누구나 가질 수 있기 때문이다 |
| `credential-profile` | key id for the secret access-key material; generation 1 is activated at assembly | | `credential-profile` | secret access key 값의 key id. 조립할 때 세대 1이 활성화된다 |
The shipped reference profile is `providers.ses` and is disabled by default. It is controlled by 내보내는 참조 profile은 `providers.ses`이고 기본으로 꺼져 있다. `APP_NOTIFICATION_PLATFORM_SES_*`로 다룬다. secret 값은
`APP_NOTIFICATION_PLATFORM_SES_*`; its secret material comes from `APP_NOTIFICATION_PLATFORM_PROVIDER_CREDENTIAL_KEY`에서 오고, 그 활성 key id는
`APP_NOTIFICATION_PLATFORM_PROVIDER_CREDENTIAL_KEY`, whose active key id must match `APP_NOTIFICATION_PLATFORM_SES_CREDENTIAL_KEY_ID`와 같아야 한다.
`APP_NOTIFICATION_PLATFORM_SES_CREDENTIAL_KEY_ID`.
`type` lists only the families the shipped composition can assemble. Current shipped `type`에는 내보내는 조립이 만들 수 있는 family만 있다. 지금 내보내는 것으로 닿는 범위는 다음과 같다.
reachability is:
| Provider type | Contract/adapter code | Shipped dispatch assembler | Shipped callback assembler | What happens when enabled for dispatch | | provider 종류 | 계약·어댑터 코드 | 내보내는 발송 assembler | 내보내는 콜백 assembler | 발송용으로 켜면 |
|---|---|---|---|---| |---|---|---|---|---|
| `SMTP` | yes | **yes** | no | assembles when Spring Mail relay settings are complete | | `SMTP` | 있음 | **있음** | 없음 | Spring Mail relay 설정이 다 있으면 조립한다 |
| `SES` | yes | **yes** | **yes** | assembles an EMAIL runtime from the typed `ses` block; SNS callback verification remains available in `INGEST_ONLY` | | `SES` | 있음 | **있음** | **있음** | 타입 있는 `ses` 블록으로 EMAIL 런타임을 조립한다. SNS 콜백 검증은 `INGEST_ONLY`에서도 쓸 수 있다 |
APNs, FCM, Twilio, Web Push and Webhook adapters used to ship as protocol code with no assembler, so APNs, FCM, Twilio, Web Push, Webhook 어댑터는 assembler 없이 프로토콜 코드로만 들어 있어서 켜면 기동이 실패했다. 그래서
enabling one failed startup. They were removed; the `docs/capability-status.md` "제거된 코드" table 지웠다. 마지막으로 그것을 가진 커밋은 `docs/capability-status.md` 「제거된 코드」 표가 적는다. family를 다시 더하려면
names the last commit that had them. Adding a family back means adding its adapter, a 그 어댑터, `ProviderRuntimeAssembler`, `ProviderType` 상수, 실제로 필요한 설정·secret 입력을 함께 더한다.
`ProviderRuntimeAssembler`, its `ProviderType` constant and the settings/secret inputs it actually
needs, together.
## SMTP relay ## SMTP relay
The one provider profile the template ships, off. A deployment that wants the common case sets 템플릿이 내보내는 provider profile 하나이고, 꺼져 있다. 흔한 경우를 원하는 배포는
`APP_NOTIFICATION_PLATFORM_SMTP_ENABLED=true` and the relay address; one that wants a different `APP_NOTIFICATION_PLATFORM_SMTP_ENABLED=true`와 relay 주소를 준다. 다른 profile id나 두 번째 family를 원하는 배포는
profile id or a second family declares it in its own YAML instead. 대신 자기 YAML에 선언한다.
The profile and the relay are separate tables below because they answer different questions. The profile과 relay는 다른 질문에 답하므로 아래 두 표로 나눈다. profile은 *어느* provider가 EMAIL을 어떤 한도로 맡는지를
profile says *which* provider serves EMAIL and under what limits; the relay says *what the transport 말하고, relay는 *전송이 무엇인지*를 말한다. host, port, 자격 증명은 여기에 아예 없다. `spring.mail.*`에 그대로 둔다.
is*. Host, port and credentials are not here at all — they stay `spring.mail.*`, because Spring Spring이 이미 그것을 가지고 있고, 두 번째 표기는 맞춰 둘 것을 하나 더 만든다.
already owns them and a second spelling would be a second thing to keep in step.
| Property | Environment variable | Default | Bound | | 속성 | 환경 변수 | 기본값 | 범위 |
|---|---|---|---| |---|---|---|---|
| `providers.smtp.enabled` | `APP_NOTIFICATION_PLATFORM_SMTP_ENABLED` | `false` | boolean | | `providers.smtp.enabled` | `APP_NOTIFICATION_PLATFORM_SMTP_ENABLED` | `false` | boolean |
| `providers.smtp.primary-for-channel` | `APP_NOTIFICATION_PLATFORM_SMTP_PRIMARY` | `true` | boolean; exactly one primary per channel | | `providers.smtp.primary-for-channel` | `APP_NOTIFICATION_PLATFORM_SMTP_PRIMARY` | `true` | boolean. 채널마다 primary는 정확히 하나 |
| `providers.smtp.environment` | `APP_NOTIFICATION_PLATFORM_SMTP_ENVIRONMENT` | `local` | required when enabled | | `providers.smtp.environment` | `APP_NOTIFICATION_PLATFORM_SMTP_ENVIRONMENT` | `local` | 켜면 필요하다 |
| `providers.smtp.credential-profile` | `APP_NOTIFICATION_PLATFORM_SMTP_CREDENTIAL_PROFILE` | `default` | resolved through `SecretMaterialProvider`, never inline material | | `providers.smtp.credential-profile` | `APP_NOTIFICATION_PLATFORM_SMTP_CREDENTIAL_PROFILE` | `default` | `SecretMaterialProvider`로 푼다. 값을 직접 적지 않는다 |
| `providers.smtp.timeout` | `APP_NOTIFICATION_PLATFORM_SMTP_TIMEOUT` | `10s` | positive, finite | | `providers.smtp.timeout` | `APP_NOTIFICATION_PLATFORM_SMTP_TIMEOUT` | `10s` | 양수, 유한 |
| `providers.smtp.max-concurrency` | `APP_NOTIFICATION_PLATFORM_SMTP_MAX_CONCURRENCY` | `4` | positive | | `providers.smtp.max-concurrency` | `APP_NOTIFICATION_PLATFORM_SMTP_MAX_CONCURRENCY` | `4` | 양수 |
| `providers.smtp.rate-per-second` | `APP_NOTIFICATION_PLATFORM_SMTP_RATE_PER_SECOND` | `10` | positive | | `providers.smtp.rate-per-second` | `APP_NOTIFICATION_PLATFORM_SMTP_RATE_PER_SECOND` | `10` | 양수 |
| Property | Environment variable | Default | Bound | | 속성 | 환경 변수 | 기본값 | 범위 |
|---|---|---|---| |---|---|---|---|
| `smtp.sender-identity` | `APP_NOTIFICATION_PLATFORM_SMTP_SENDER_IDENTITY` | `no-reply@example.invalid` | address | | `smtp.sender-identity` | `APP_NOTIFICATION_PLATFORM_SMTP_SENDER_IDENTITY` | `no-reply@example.invalid` | 주소 |
| `smtp.dispatch-concurrency` | `APP_NOTIFICATION_PLATFORM_SMTP_DISPATCH_CONCURRENCY` | `4` | positive | | `smtp.dispatch-concurrency` | `APP_NOTIFICATION_PLATFORM_SMTP_DISPATCH_CONCURRENCY` | `4` | 양수 |
SMTP transport configuration has one owner: Spring Mail. The actual `JavaMailSenderImpl` must use required STARTTLS (`mail.smtp.starttls.enable=true` plus `mail.smtp.starttls.required=true`) or implicit TLS (`mail.smtp.ssl.enable=true`). It must also have positive `mail.smtp.connectiontimeout`, `mail.smtp.timeout`, and `mail.smtp.writetimeout` values. SMTP assembly fails before serving traffic when those properties are absent or invalid. SMTP 전송 설정의 소유자는 Spring Mail 하나다. 실제 `JavaMailSenderImpl`은 필수 STARTTLS
(`mail.smtp.starttls.enable=true`와 `mail.smtp.starttls.required=true`)나 암묵적 TLS(`mail.smtp.ssl.enable=true`)를
써야 한다. `mail.smtp.connectiontimeout`, `mail.smtp.timeout`, `mail.smtp.writetimeout`도 양수여야 한다. 이 속성이
없거나 틀리면 SMTP 조립이 트래픽을 받기 전에 실패한다.
The native environment contract is `SPRING_MAIL_HOST`, `SPRING_MAIL_PORT`, optional 환경 변수 계약은 Spring 그대로다. `SPRING_MAIL_HOST`, `SPRING_MAIL_PORT`, 선택인 `SPRING_MAIL_USERNAME`과 secret
`SPRING_MAIL_USERNAME` / secret `SPRING_MAIL_PASSWORD`, plus the `SPRING_MAIL_PASSWORD`, 그리고 `.env.example`에 있는 `SPRING_MAIL_PROPERTIES_MAIL_SMTP_*` TLS·시간 상한 키다. Spring
`SPRING_MAIL_PROPERTIES_MAIL_SMTP_*` TLS and timeout keys listed in `.env.example`. These names stay Boot 자신이 `spring.mail.*`를 가지고 읽으므로 이름을 Spring 그대로 둔다. 알림 모듈은 같은 relay에 두 번째 별칭을
Spring-native because Spring Boot itself owns and consumes `spring.mail.*`; the notification module 만들지 않는다.
does not create a second alias for the same relay.
The default sender is an RFC 2606 reserved domain that resolves nowhere, so a deployment that forgot 기본 보내는 주소는 어디로도 풀리지 않는 RFC 2606 예약 도메인이다. 그래서 보내는 주소 설정을 잊은 배포는, 자기가
to set one produces a traceable bounce instead of mail apparently sent from an address it does not 가지지 않은 주소로 메일을 보낸 것처럼 보이는 대신 추적할 수 있는 bounce를 낸다.
own.
## Startup failures ## 기동 실패
Startup fails rather than degrading when: 다음이면 기능을 줄여 뜨지 않고 기동이 실패한다.
- a payload or queue setting is unbounded - payload나 큐 설정에 상한이 없다
- a timeout is negative - 시간 상한이 음수다
- a TTL-required profile has no expiry source - TTL이 필요한 profile에 만료 출처가 없다
- a callback signing secret is missing - 콜백 서명 secret이 없다
- a production profile enables trust-all - 운영 profile이 trust-all을 켠다
- an SES profile is missing its `ses` block, or callbacks are on and `ses.allowed-topic-arns` is empty - SES profile에 `ses` 블록이 없거나, 콜백이 켜졌는데 `ses.allowed-topic-arns`가 비어 있다
- two provider profiles share an id - 두 provider profile의 id가 같다
- a route points only at disabled providers - route가 꺼진 provider만 가리킨다
- `mode` is `SERVING` and no provider profile is enabled - `mode`가 `SERVING`인데 켜진 provider profile이 없다
- the notification schema stream is not applied and promoted - 알림 스키마 stream이 적용·승격되지 않았다
## Secrets ## secret
All key material arrives through `SecretMaterialProvider`. Nothing is read from source, from a 키 값은 모두 `SecretMaterialProvider`로 들어온다. 소스, 커밋한 파일, 평문 로그에서는 아무것도 읽지 않는다. 연락처
committed file, or from a plaintext log. Contact point encryption and lookup HMAC keys must be 암호화 키와 조회 HMAC 키는 서로 달라야 하고, 암호화 키는 정확히 256비트여야 한다.
distinct, and the encryption key must be exactly 256 bits.
Seven purposes, seven keys. Each is base64 of at least 32 bytes and each must differ from every 목적 일곱, 키 일곱이다. 각각 32바이트 이상의 base64이고 다른 모든 키와 달라야 한다. 플랫폼은 기동할 때 키를 풀어
other; the platform decodes them at startup and refuses to boot if one is blank, short or shared. A 보고, 하나라도 비었거나 짧거나 겹치면 뜨기를 거부한다. 전에는 빈 값을 건너뛰었고, 그래서 플랫폼이 키 없이 뜬 뒤 첫
blank value used to be skipped, which meant the platform started without the key and found out on 연락처에서야, 운영에서는 수신자의 알림에서야 그것을 알았다.
the first contact point — in production, on a recipient's notification.
Every default below is **unset**, deliberately. Supply the values out of band, per environment. Do 아래 기본값은 모두 일부러 **비어 있다**. 값은 환경마다 따로 준다. 이 표, `application.yml`, 추적되는 `.env` 파일, 어느
not write one into this table, into `application.yml`, into an `.env` file that is tracked, or into 예시에도 값을 쓰지 않는다. 저장소에 나타난 값은 이미 드러난 값이다.
any example: a value that appears in the repository is a value that has been disclosed.
| Purpose | Key material | Active key id | | 목적 | 키 값 | 활성 key id |
|---|---|---| |---|---|---|
| Contact point encryption | `APP_NOTIFICATION_PLATFORM_CONTACT_ENCRYPTION_KEY` | `APP_NOTIFICATION_PLATFORM_CONTACT_ENCRYPTION_KEY_ID` | | 연락처 암호화 | `APP_NOTIFICATION_PLATFORM_CONTACT_ENCRYPTION_KEY` | `APP_NOTIFICATION_PLATFORM_CONTACT_ENCRYPTION_KEY_ID` |
| Contact point lookup HMAC | `APP_NOTIFICATION_PLATFORM_CONTACT_LOOKUP_HMAC_KEY` | `APP_NOTIFICATION_PLATFORM_CONTACT_LOOKUP_HMAC_KEY_ID` | | 연락처 조회 HMAC | `APP_NOTIFICATION_PLATFORM_CONTACT_LOOKUP_HMAC_KEY` | `APP_NOTIFICATION_PLATFORM_CONTACT_LOOKUP_HMAC_KEY_ID` |
| Callback signing | `APP_NOTIFICATION_PLATFORM_CALLBACK_SIGNING_KEY` | `APP_NOTIFICATION_PLATFORM_CALLBACK_SIGNING_KEY_ID` | | 콜백 서명 | `APP_NOTIFICATION_PLATFORM_CALLBACK_SIGNING_KEY` | `APP_NOTIFICATION_PLATFORM_CALLBACK_SIGNING_KEY_ID` |
| Callback fingerprint HMAC | `APP_NOTIFICATION_PLATFORM_CALLBACK_FINGERPRINT_HMAC_KEY` | `APP_NOTIFICATION_PLATFORM_CALLBACK_FINGERPRINT_HMAC_KEY_ID` | | 콜백 fingerprint HMAC | `APP_NOTIFICATION_PLATFORM_CALLBACK_FINGERPRINT_HMAC_KEY` | `APP_NOTIFICATION_PLATFORM_CALLBACK_FINGERPRINT_HMAC_KEY_ID` |
| Provider credential encryption | `APP_NOTIFICATION_PLATFORM_PROVIDER_CREDENTIAL_KEY` | `APP_NOTIFICATION_PLATFORM_PROVIDER_CREDENTIAL_KEY_ID` | | provider 자격 증명 암호화 | `APP_NOTIFICATION_PLATFORM_PROVIDER_CREDENTIAL_KEY` | `APP_NOTIFICATION_PLATFORM_PROVIDER_CREDENTIAL_KEY_ID` |
| Provider request lookup HMAC | `APP_NOTIFICATION_PLATFORM_PROVIDER_REQUEST_LOOKUP_HMAC_KEY` | `APP_NOTIFICATION_PLATFORM_PROVIDER_REQUEST_LOOKUP_HMAC_KEY_ID` | | provider 요청 조회 HMAC | `APP_NOTIFICATION_PLATFORM_PROVIDER_REQUEST_LOOKUP_HMAC_KEY` | `APP_NOTIFICATION_PLATFORM_PROVIDER_REQUEST_LOOKUP_HMAC_KEY_ID` |
| Payload encryption | `APP_NOTIFICATION_PLATFORM_PAYLOAD_ENCRYPTION_KEY` | `APP_NOTIFICATION_PLATFORM_PAYLOAD_ENCRYPTION_KEY_ID` | | payload 암호화 | `APP_NOTIFICATION_PLATFORM_PAYLOAD_ENCRYPTION_KEY` | `APP_NOTIFICATION_PLATFORM_PAYLOAD_ENCRYPTION_KEY_ID` |
A key id is not secret — an id identifies key material without revealing it — but it is required, key id는 secret이 아니다. id는 키 값을 드러내지 않고 그것을 가리킨다. 그래도 필요하고, 일부러 기본값이 없다. 고정된
and it has no default on purpose. A constant id makes a rotation indistinguishable from the key it id는 교체를 바뀌기 전 키와 구별할 수 없게 만들어서, 그 전에 쓴 것을 아무것도 풀지 못하게 한다. 키 값을 바꾸는 배포에서
replaced, so nothing could decrypt what was written before it. Change the id in the same deployment id도 함께 바꾸고, 밀려난 키는 그 키로 쓴 데이터를 다시 암호화할 때까지 옛 id로 읽을 수 있게 둔다. 교체 순서는
that changes the material, and keep the superseded key readable under its old id until the data it [at-rest-threat-model.md](at-rest-threat-model.md)에 있다.
wrote has been re-encrypted. The rotation sequence is in
[at-rest-threat-model.md](at-rest-threat-model.md).
## Readiness ## readiness
The platform contributes a `notifications` actuator endpoint and a health indicator. It reports DOWN 플랫폼은 `notifications` actuator 엔드포인트와 health indicator를 보탠다. provider 자격 증명이 거부됐을 때, 설정된
when a provider's credentials were rejected, when a configured provider has no channel route, and provider에 채널 route가 없을 때, 그리고 잰 backlog, 멈춘 lease 수, projection 지연, 맞추기(reconciliation) 지연이
when the measured backlog, stuck-lease count, projection lag or reconciliation lag passes the `NotificationServingThresholds`의 임계값을 넘을 때 DOWN을 보고한다. [operations.md](operations.md)를 본다.
thresholds in `NotificationServingThresholds`. See [operations.md](operations.md).
+29 -32
View File
@@ -1,6 +1,6 @@
# Delivery evidence model # 전달 증거 모델
## The shape ## 모양
```text ```text
NotificationRequest NotificationRequest
@@ -12,39 +12,37 @@ NotificationRequest
+ EngagementFacts + SuppressionFacts + EngagementFacts + SuppressionFacts
``` ```
Four identities, four lifecycles. A logical request is not a recipient job, a recipient job is not a 신원 넷, 수명 주기 넷이다. 논리 요청은 수신자 작업이 아니고, 수신자 작업은 provider attempt가 아니고, provider attempt는
provider attempt, and a provider attempt is not the event stream that describes it. 그것을 설명하는 이벤트 흐름이 아니다.
## Why not one status enum ## 상태 enum 하나가 아닌 이유
A single linear status would have to answer "what happened?" with one value, and the real answers do 일직선 상태 하나는 「무슨 일이 있었나」에 값 하나로 답해야 하는데, 실제 답은 한 줄에 들어가지 않는다.
not fit on one line:
- An email can be `DELIVERED` and then generate a complaint. Both facts are true and both matter: - 이메일은 `DELIVERED`가 된 뒤 complaint를 낼 수 있다. 두 사실이 다 참이고 다 중요하다. 하나는 보고에, 다른 하나는
one for reporting, the other for suppression. 억제에 쓴다.
- Twilio does not guarantee callback ordering, so `sent` routinely arrives after `delivered`. Under - Twilio는 콜백 순서를 보장하지 않아서 `sent`가 `delivered` 뒤에 오는 일이 흔하다. 순번 규칙에서는 뒤에 온 약한
an ordinal rule the later, weaker event silently overwrites the stronger one. 이벤트가 강한 이벤트를 조용히 덮어쓴다.
- APNs may accept a notification and then store, replace or discard it. - APNs는 알림을 수락한 뒤 저장하거나, 바꾸거나, 버릴 수 있다.
So the ledger stores events and a channel projector merges them through an explicit transition table. 그래서 ledger는 이벤트를 저장하고, channel projector가 명시한 전이 표로 그것을 합친다. 공통 규칙은
`StandardDeliveryProjector` holds the shared rules; provider projectors add only their own event `StandardDeliveryProjector`가 가지고, provider projector는 자기 이벤트 어휘만 더한다.
vocabulary.
## Merge rules ## 합치는 규칙
| Transition | Result | | 전이 | 결과 |
|---|---| |---|---|
| `sent` → `delivered` | applied | | `sent` → `delivered` | 적용 |
| `delivered` → `sent` | ignored, event still stored | | `delivered` → `sent` | 무시, 이벤트는 저장 |
| `delivered` → `complaint` | complaint fact added, delivery preserved | | `delivered` → `complaint` | complaint 사실을 더하고 전달은 유지 |
| `complaint` → `delivered` | delivery applied, complaint preserved | | `complaint` → `delivered` | 전달을 적용하고 complaint는 유지 |
| `accepted` → `bounced` | applied | | `accepted` → `bounced` | 적용 |
| `read` → `displayed` | ignored | | `read` → `displayed` | 무시 |
| hard bounce → `delivered` | ignored, hard bounce is terminal | | hard bounce → `delivered` | 무시, hard bounce는 끝 상태 |
Engagement (`opened`, `clicked`) is stored beside the delivery outcome and never changes it. 참여(`opened`, `clicked`)는 전달 결과 옆에 저장하고 그것을 바꾸지 않는다.
## Ambiguity ## 모호함
```text ```text
platform ──── send ────▶ provider platform ──── send ────▶ provider
@@ -53,10 +51,9 @@ platform ──── send ────▶ provider
✗ connection reset ✗ connection reset
``` ```
The platform may hold no provider request id while the notification really was sent. The attempt 알림이 실제로 보내졌는데 플랫폼은 provider request id를 하나도 가지지 못할 수 있다. attempt는 `requestStarted`,
records `requestStarted`, `requestBodyCommitted`, `providerResponseReceived` and an `requestBodyCommitted`, `providerResponseReceived`와 그 각각의 `EvidenceCertainty`를 기록한다. 그래서 나중의 판단이
`EvidenceCertainty` for each, so a later decision can tell "we know nothing was sent" apart from "we 「아무것도 보내지 않았음을 안다」와 「답을 읽지 못했다」를 가릴 수 있다.
could not read the answer".
`ProviderSubmissionResult` enforces this: an ambiguous result may not claim `PROVIDER_ACCEPTED`, and `ProviderSubmissionResult`가 이것을 강제한다. 모호한 결과는 `PROVIDER_ACCEPTED`를 주장할 수 없고, 어떤 제출 결과도
no submission result of any kind may carry a delivery outcome. 전달 결과를 실을 수 없다.
+24 -31
View File
@@ -1,45 +1,38 @@
# Migration guide # 이행 안내
## From the R0 routing seam ## R0 routing seam에서
The pre-existing `dev.caskeleton.adapter.outbound.notification` router (`RoutingNotifier`, 이미 있던 `dev.caskeleton.adapter.outbound.notification` router(`RoutingNotifier`, `FailOpenNotificationProvider`, Google
`FailOpenNotificationProvider`, the Google email and Slack webhook seams) stays untouched. The email과 Slack webhook seam)는 건드리지 않는다. 전달 플랫폼은 그 옆 `…notification.platform` 아래에 있고, R0 클래스를
delivery platform lives beside it under `…notification.platform` and does not modify or delete any 고치거나 지우지 않는다.
R0 class.
Migration order per capability: capability마다 이행 순서:
1. Register the contact points behind `ContactPointStorePort` so the platform owns protected values. 1. 플랫폼이 보호된 값을 가지도록 연락처를 `ContactPointStorePort` 뒤에 등록한다.
2. Publish the template version, and pin the template id, version and locale at every call site. 2. 템플릿 버전을 게시하고, 모든 호출 지점에서 템플릿 id, 버전, locale을 고정한다.
3. Move the call site from the router to the N1 typed facade for the channel. 3. 호출 지점을 router에서 그 채널의 N1 typed facade로 옮긴다.
4. Verify evidence in the snapshot rather than in the caller's return value: `submit()` is durable 4. 증거는 호출자의 반환값이 아니라 snapshot에서 확인한다. `submit()`은 durable 수락일 뿐이다.
acceptance and nothing more. 5. 대상 환경에서 플랫폼 route가 provider 증거를 낸 뒤에만 R0 route를 지운다.
5. Remove the R0 route only after the platform route has produced provider evidence in the target
environment.
## Return-value semantics change ## 반환값의 뜻이 바뀐다
The R0 seam returned a send-shaped result. `NotificationReceipt` returns `notificationId`, a request R0 seam은 보낸 결과 모양을 돌려줬다. `NotificationReceipt`는 `notificationId`, 요청 상태, 수락 시각을 돌려준다. 옛
status and an acceptance time. Callers that treated the old return value as proof of delivery must be 반환값을 전달 증거로 다룬 호출자는 고쳐야 한다. 호환 shim은 없다. shim은 이 플랫폼이 피하려고 있는 전달 주장을 지어내야
changed; there is no compatibility shim, because a shim would have to invent the delivery claim this 하기 때문이다.
platform exists to avoid.
## FCM target migration ## FCM 대상 이행
Registration tokens keep working through `LegacyFcmRegistrationToken`. New registrations should use registration token은 `LegacyFcmRegistrationToken`으로 계속 쓸 수 있다. 새 등록은 `FcmInstallationId`를 쓴다. 둘은 서로
`FcmInstallationId`. The two are distinct types, so a migration is a compile-time task rather than a 다른 타입이라 이행은 런타임 짐작이 아니라 컴파일 시점의 일이다.
runtime guess.
## R1의 처분 (NOTIF-ADR-005) ## R1의 처분 (NOTIF-ADR-005)
이 문서는 R0 router → platform 이행만 설명해 왔고, `dev.caskeleton.application.notification` 직속의 이 문서는 R0 router → platform 이행만 설명해 왔고, `dev.caskeleton.application.notification` 직속의 R1 public type
R1 public type 100개를 어떻게 할 것인지 다루지 않았다. 그래서 새 consumer가 어느 API를 써야 하는지 100개를 어떻게 할 것인지 다루지 않았다. 그래서 새 consumer가 어느 API를 써야 하는지 문서 어디에도 답이 없었다.
문서 어디에도 답이 없었다.
- **canonical은 `..notification.platform..`이다.** NOTIF-ADR-005가 근거와 함께 정한다. - **canonical은 `..notification.platform..`이다.** NOTIF-ADR-005가 근거와 함께 정한다.
- **application R1 public type은 2026-09-25에 삭제했다.** production consumer가 0건이었다. 남은 것은 - **application R1 public type은 2026-09-25에 삭제했다.** production consumer가 0건이었다. 남은 것은 단순 알림 포트
단순 알림 포트 `NotificationPort`·`Notification`·`NotificationChannel`뿐이다. `NotificationPort`·`Notification`·`NotificationChannel`뿐이다.
- R1을 따라 만들어졌지만 composition root에서 한 번도 조립되지 않았던 outbound adapter의 - R1을 따라 만들어졌지만 composition root에서 한 번도 조립되지 않았던 outbound adapter의 `catalog/`, `provider/`,
`catalog/`, `provider/`, `template/` 실험 구현도 제거했다. 실제 runtime은 `template/` 실험 구현도 제거했다. 실제 runtime은 `dev.caskeleton.adapter.outbound.notification.platform..`만 사용한다.
`dev.caskeleton.adapter.outbound.notification.platform..`만 사용한다.
- 삭제 목록과 마지막 커밋은 `docs/capability-status.md`의 「제거된 코드」 표에 있다. - 삭제 목록과 마지막 커밋은 `docs/capability-status.md`의 「제거된 코드」 표에 있다.
+61 -73
View File
@@ -1,39 +1,37 @@
# Notification Delivery Platform — module mapping # 알림 전달 플랫폼 — 모듈 대응표
> Source design: `docs/design/2026-08-10-notification-platform-design.md` > 출처 설계서: `docs/design/2026-08-10-notification-platform-design.md`
> >
> Source plan: `docs/history/plans/2026-08-10-notification-platform-implementation-plan.md` > 출처 계획서: `docs/history/plans/2026-08-10-notification-platform-implementation-plan.md`
## Why a mapping exists ## 대응표가 있는 이유
The plan was written against a hypothetical repository (`modules/notification/**`, root package 계획은 가상의 저장소(`modules/notification/**`, root 패키지 `io.backend.skeleton.notification`, Gradle 프로젝트 31개)를
`io.backend.skeleton.notification`, 31 Gradle projects). This repository is a fail-closed 두고 쓰였다. 이 저장소는 fail-closed Clean Architecture 템플릿이다. `src/settings.gradle`은 registry
19-leaf Clean Architecture template: `src/settings.gradle` rejects any registry that does not (`src/config/architecture/modules.json`)를 읽고 검증한 뒤 등록된 프로젝트만 들이고, `verifyCleanArchitectureDependencies`는
contain exactly the 19 modules in `src/config/architecture/modules.json`, and `allowed_dependencies` 밖의 프로젝트 edge를 거부한다.
`verifyCleanArchitectureDependencies` rejects any project edge outside `allowed_dependencies`.
Creating 31 new Gradle projects would violate HARD-STOP #5 of `AGENTS.md`. The package README Gradle 프로젝트 31개를 새로 만들면 `AGENTS.md`의 HARD-STOP #5를 어긴다. 패키지 README도 이것을 내다보고, 공개 계약과
anticipates this and instructs the implementer to map dependency catalog and package/file paths onto 신뢰성 의미를 지키면서 의존성 카탈로그와 패키지·파일 경로를 받는 저장소의 규칙에 맞추라고 구현자에게 지시한다.
the host repository's rules while preserving the public contracts and reliability semantics.
Every logical module of the plan is therefore implemented as a **package** inside the registered leaf 그래서 계획의 논리 모듈마다 그 책임을 가진 등록 leaf 안의 **패키지**로 구현했다. 공개 계약, 증거 규칙, 신뢰성 의미는
that owns its responsibility. No public contract, evidence rule, or reliability semantic is dropped. 하나도 빠지지 않았다.
## Logical module → registered leaf ## 논리 모듈 → 등록 leaf
| Plan module | Registered leaf | Package | | 계획 모듈 | 등록 leaf | 패키지 |
|---|---|---| |---|---|---|
| `notification-core-api` | `application-core` | `dev.caskeleton.application.notification.platform.api` | | `notification-core-api` | `application-notification` | `dev.caskeleton.application.notification.platform.api` |
| `notification-content-api` | `application-core` | `…platform.api.content` | | `notification-content-api` | `application-notification` | `…platform.api.content` |
| `notification-contact-api` | `application-core` | `…platform.contact` | | `notification-contact-api` | `application-notification` | `…platform.contact` |
| `notification-template-api` | `application-core` | `…platform.template` | | `notification-template-api` | `application-notification` | `…platform.template` |
| `notification-policy` | `application-core` | `…platform.policy` | | `notification-policy` | `application-notification` | `…platform.policy` |
| `notification-provider-spi` | `application-core` | `…platform.provider` | | `notification-provider-spi` | `application-notification` | `…platform.provider` |
| `notification-callback-api` | `application-core` | `…platform.callback` | | `notification-callback-api` | `application-notification` | `…platform.callback` |
| `notification-inbox-api` | `application-core` | `…platform.inbox` | | `notification-inbox-api` | `application-notification` | `…platform.inbox` |
| `notification-admin-api` | `application-core` | `…platform.admin` | | `notification-admin-api` | `application-notification` | `…platform.admin` |
| `notification-security` (ports) | `application-core` | `…platform.security` | | `notification-security` (ports) | `application-notification` | `…platform.security` |
| `notification-observability` (ports) | `application-core` | `…platform.observation` | | `notification-observability` (ports) | `application-notification` | `…platform.observation` |
| `notification-dispatch-runtime` | `adapter:outbound:notification` | `dev.caskeleton.adapter.outbound.notification.platform.dispatch` | | `notification-dispatch-runtime` | `adapter:outbound:notification` | `dev.caskeleton.adapter.outbound.notification.platform.dispatch` |
| `notification-security` (AES-GCM/HMAC impl) | `adapter:outbound:notification` | `…platform.security` | | `notification-security` (AES-GCM/HMAC impl) | `adapter:outbound:notification` | `…platform.security` |
| `notification-template-thymeleaf` (reference renderer) | `adapter:outbound:notification` | `…platform.template` | | `notification-template-thymeleaf` (reference renderer) | `adapter:outbound:notification` | `…platform.template` |
@@ -42,20 +40,20 @@ that owns its responsibility. No public contract, evidence rule, or reliability
| `notification-observability` (Micrometer impl) | `adapter:outbound:notification` | `…platform.observation` | | `notification-observability` (Micrometer impl) | `adapter:outbound:notification` | `…platform.observation` |
| `notification-admin-runtime` | `adapter:outbound:notification` | `…platform.admin` | | `notification-admin-runtime` | `adapter:outbound:notification` | `…platform.admin` |
| `notification-spring-boot-starter` | `adapter:outbound:notification` | `…platform.autoconfigure` | | `notification-spring-boot-starter` | `adapter:outbound:notification` | `…platform.autoconfigure` |
| `notification-persistence-jpa` | `adapter:outbound:persistence-notification` | `dev.caskeleton.adapter.outbound.persistence.notification.platform` (store adapters), `….platform.entity` (JPA rows), `….platform.repository` (Spring Data interfaces and SQL text) | | `notification-persistence-jpa` | `adapter:outbound:persistence-notification` | `dev.caskeleton.adapter.outbound.persistence.notification.platform`(저장소 어댑터), `….platform.entity`(JPA 행), `….platform.repository`(Spring Data interface와 SQL 문) |
| `notification-inbox-jpa` | `adapter:outbound:persistence-notification` | `…persistence.notification.platform` (`JpaNotificationInbox`, `InboxCommitEventPublisher`, `InboxOutboxRecordFactory`); row and repository in `….platform.entity` / `….platform.repository` | | `notification-inbox-jpa` | `adapter:outbound:persistence-notification` | `…persistence.notification.platform`(`JpaNotificationInbox`, `InboxCommitEventPublisher`, `InboxOutboxRecordFactory`). 행과 repository는 `….platform.entity` / `….platform.repository` |
| `notification-callback-mvc` | `adapter:inbound:web-notification` | `dev.caskeleton.adapter.inbound.web.notification.platform.callback` | | `notification-callback-mvc` | `adapter:inbound:web-notification` | `dev.caskeleton.adapter.inbound.web.notification.platform.callback` |
| `notification-submission-mvc` | `adapter:inbound:web-notification` | `dev.caskeleton.adapter.inbound.web.notification.platform.submission` | | `notification-submission-mvc` | `adapter:inbound:web-notification` | `dev.caskeleton.adapter.inbound.web.notification.platform.submission` |
| application composition (use cases, callback bridge, `config/module-defaults/notification.yml`) | `composition:notification-platform` | `dev.caskeleton.composition.notification` | | 애플리케이션 조립(use case, 콜백 bridge, `config/module-defaults/notification.yml`) | `composition:notification-platform` | `dev.caskeleton.composition.notification` |
| `notification-testkit` | test source sets of the owning leaves | `…platform.testkit` | | `notification-testkit` | 소유 leaf의 test source set | `…platform.testkit` |
## Dependency-direction consequences ## 의존 방향의 결과
The plan's module DAG (`*-api` → `provider-spi`/`policy` → runtime/adapters → starter) is preserved 계획의 모듈 DAG(`*-api` → `provider-spi`/`policy` → runtime/adapters → starter)는 registry가 이미 강제하는 leaf DAG로
by the leaf DAG that the registry already enforces: 지켜진다.
```text ```text
application-core (all *-api, provider SPI, policy, callback contracts) application-notification (all *-api, provider SPI, policy, callback contracts; → application-core)
↑ ↑ ↑ ↑ ↑ ↑
adapter:outbound:notification adapter:outbound:persistence-notification adapter:inbound:web-notification adapter:outbound:notification adapter:outbound:persistence-notification adapter:inbound:web-notification
↑ ↑ (runtimeOnly, with persistence-jpa) ↑ (→ adapter:inbound:web) ↑ ↑ (runtimeOnly, with persistence-jpa) ↑ (→ adapter:inbound:web)
@@ -64,50 +62,40 @@ adapter:outbound:notification adapter:outbound:persistence-notification ad
app-bootstrap (one line) app-bootstrap (one line)
``` ```
Two plan edges cannot be expressed as project edges in this repository, and are replaced by ports: 계획의 edge 둘은 이 저장소에서 프로젝트 edge로 표현할 수 없어서 port로 바꿨다.
1. `notification-email-ses` → `httpclient platform`. (The Twilio, FCM, APNs, Web Push and 1. `notification-email-ses` → `httpclient platform`. (이 edge를 함께 쓰던 Twilio, FCM, APNs, Web Push, Webhook 어댑터는
Webhook adapters that shared this edge were removed: none had an assembler.) assembler가 없어서 지웠다.) `adapter-outbound-notification`은 `adapter-outbound-httpclient`에 의존할 수 없고, SES는
`adapter-outbound-notification` is not allowed to depend on `adapter-outbound-httpclient`, and 이제 그것이 필요 없다. SES 어댑터는 스스로 요청에 서명하는 AWS SDK v2 `sesv2` 클라이언트로 보낸다(소유자 결정 17).
SES no longer needs it: the SES adapter sends through the AWS SDK v2 `sesv2` client (owner 어댑터 안의 JDK HTTP gateway와 SigV4 signer는 그 변경과 함께 지웠다. 클라이언트는 profile마다 SDK 재시도를 끄고,
decision 17), which signs requests itself. The adapter-local JDK HTTP gateway and SigV4 signer 기본 credential chain 없이(요청마다 자기 profile의 자격 증명을 싣는다), profile의 endpoint로 만든다. 그 endpoint는
were deleted with that change. The client is built per profile with SDK retries off, no default 여전히 알림 routability guard를 통과한다.
credential chain (each request carries its profile's credential) and the profile's endpoint, 2. `notification-inbox-jpa` → `optional messaging outbox integration`. `adapter-outbound-persistence-notification`은
which still passes the notification routability guard. `adapter-outbound-messaging`에 의존할 수 없다. inbox는 이미 있는 persistence outbox 테이블과 애플리케이션 port
2. `notification-inbox-jpa` → `optional messaging outbox integration`. `NotificationInboxSignalPort`로 내보내고, outbox relay는 `composition:outbox-relay`가 조립한다.
`adapter-outbound-persistence-notification` may not depend on `adapter-outbound-messaging`; the inbox
publishes through the existing persistence outbox tables plus the
`NotificationInboxSignalPort` application port, and `app-bootstrap` binds the relay.
## Commit policy ## 커밋 정책
`AGENTS.md` pins commit policy to `human-only`. Step 5 (`git add` / `git commit`) of every plan task `AGENTS.md`는 커밋 정책을 `human-only`로 고정한다. 그래서 계획의 모든 task에 있는 Step 5(`git add` / `git commit`)는
is therefore intentionally **not** executed by the agent; the working tree carries the change and the 에이전트가 일부러 **하지 않았다**. 작업 트리가 변경을 싣고, 사람 소유자가 커밋한다.
human owner commits.
## Runtime reachability after the R1 adapter cleanup ## R1 어댑터 정리 뒤 런타임 도달 범위
The application R1 contract covered by NOTIF-ADR-005 is a separate question from the abandoned NOTIF-ADR-005가 다루는 애플리케이션 R1 계약은, 그것을 둘러싸고 만들었다가 버린 outbound 구현과는 다른 문제다. 뒤의 것은
outbound implementation that had been built around it. The latter is gone: the notification leaf no 없어졌다. 알림 leaf에는 최상위 `catalog/`, `provider/`, `template/` R1 어댑터 패키지가 더는 없다. 그것들은 운영 조립의
longer contains top-level `catalog/`, `provider/`, or `template/` R1 adapter packages. They had no consumer가 없었고 자기 fake로만 증명됐다.
production composition consumer and were proved only by their own fakes.
The useful rendering invariant from that experiment was not discarded. R2 그 실험의 쓸모 있던 렌더링 불변식은 버리지 않았다. R2 `platform.template.TemplateSlotPolicy`가 이제 치환한 값을
`platform.template.TemplateSlotPolicy` now validates the final HTML against the reviewed tag and escape하는 것에 더해, 최종 HTML을 검토한 태그·속성 부분집합과 대조한다. 실행되는 script markup, event handler 속성,
attribute subset in addition to escaping substituted values. Active script markup, event-handler HTTPS가 아닌 HTML 링크는 거부한다.
attributes and non-HTTPS HTML links are refused.
R2 provider protocol packages remain because they implement the canonical platform SPI and have R2 provider 프로토콜 패키지는 canonical 플랫폼 SPI를 구현하고 계약 테스트가 있어서 남아 있다. 남은 것은 `ses`와
contract tests. Their presence does **not** make them shipped dispatch runtimes. Current composition `smtp`이고, 둘 다 내보내는 조립이 발송에 쓴다(SES는 콜백 받기에도 쓴다). 다른 family는 조립이 그 family에 필요한 설정·secret
reachability is SMTP and SES for dispatch, with SES also available for callback ingestion; the remaining 출처와 함께 `ProviderRuntimeAssembler`를 보탤 때 생긴다. 표는 `support-matrix.md`에 있다.
provider packages are extension assets until a composition contributes a `ProviderRuntimeAssembler`
with the settings and secret sources that family requires. See `support-matrix.md` for the explicit table.
## R1 public types (NOTIF-ADR-005) ## R1 public type (NOTIF-ADR-005)
NOTIF-ADR-005 made `..notification.platform..` canonical. The R1 types directly under NOTIF-ADR-005가 `..notification.platform..`을 canonical로 정했다. `dev.caskeleton.application.notification` 바로 아래의
`dev.caskeleton.application.notification` had no production consumer and were removed on R1 타입은 운영 consumer가 없어서, 두 namespace를 떼어 놓던 ArchUnit 규칙과 함께 2026-09-25에 지웠다. 거기 남은 것은
2026-09-25, together with the ArchUnit rule that kept the two namespaces apart. What remains there 어댑터 core가 구현하는 단순 알림 port `NotificationPort`, `Notification`, `NotificationChannel`이다. 지운 타입과 마지막
is the simple notification port the adapter core implements — `NotificationPort`, `Notification`, 커밋은 `docs/capability-status.md` 「제거된 코드」에 있다.
`NotificationChannel`. The removed types and their last commit are listed in
`docs/capability-status.md` under "제거된 코드".
+21 -25
View File
@@ -1,6 +1,6 @@
# Operations # 운영
## Runtime shape ## 런타임 모양
```text ```text
durable queue (PostgreSQL, FOR UPDATE SKIP LOCKED) durable queue (PostgreSQL, FOR UPDATE SKIP LOCKED)
@@ -12,35 +12,31 @@ durable queue (PostgreSQL, FOR UPDATE SKIP LOCKED)
→ provider adapter → provider adapter
``` ```
Provider calls run outside every database transaction. The attempt row is committed first, so after a provider 호출은 모든 DB 트랜잭션 밖에서 돈다. attempt 행을 먼저 커밋하므로, 장애 뒤 그 행은 없거나(아무것도 보내지
crash the row is either absent (nothing was sent) or present in `DISPATCHING` (reconciliation has 않음) `DISPATCHING`으로 있다(맞추기가 물어볼 것이 있음).
something to ask about).
## Guards that exist for specific incidents ## 특정 장애를 막으려고 있는 장치
| Guard | The incident it prevents | | 장치 | 막는 장애 |
|---|---| |---|---|
| Credential failure opens the provider route | One expired key multiplied by a queue becomes a self-inflicted outage | | 자격 증명 실패가 provider route를 연다 | 만료된 키 하나가 큐만큼 곱해져 스스로 만든 장애가 된다 |
| Retry budget per provider profile | A provider outage turning every queued notification into its own retry loop | | provider profile마다 재시도 예산 | provider 장애가 큐의 모든 알림을 저마다의 재시도 반복으로 만든다 |
| Ambiguous attempts block automatic fallback | A push whose response was lost arriving alongside the "just in case" SMS | | 모호한 attempt는 자동 전환을 막는다 | 응답을 잃은 push와 「혹시 몰라」 보낸 SMS가 함께 도착한다 |
| Permits released during backoff | A slow provider pinning the whole concurrency budget on work that is only waiting | | 백오프 동안 허가를 돌려준다 | 느린 provider가 기다리기만 하는 일로 동시성 예산 전체를 붙잡는다 |
| Fail-fast intake on capacity | An unbounded in-memory queue absorbing a burst it cannot survive | | 용량이 차면 받기를 바로 거부한다 | 상한 없는 메모리 큐가 버틸 수 없는 폭주를 받아들인다 |
## Scheduling ## 일정
`scheduleAt` activates the job, `notBefore` is the earliest permitted provider submission, and `scheduleAt`은 작업을 활성화하고, `notBefore`는 provider 제출을 허용하는 가장 이른 시각이고, `expiresAt`은 새 attempt,
`expiresAt` blocks new attempts, retries and fallbacks. Suppression and expiry are re-checked 재시도, 전환을 막는다. 억제와 만료는 발송 직전에 다시 확인한다. 예약된 알림은 큐에서 몇 시간을 기다릴 수 있고, 그동안
immediately before dispatch, because a scheduled notification can sit in the queue for hours and the 사용자가 수신을 거부했을 수 있다.
user may have opted out in the meantime.
## Redrive ## 다시 보내기(redrive)
A redrive preserves `NotificationId` and `RecipientDeliveryId`, creates a new `DeliveryAttemptId`, and redrive는 `NotificationId`와 `RecipientDeliveryId`를 유지하고, 새 `DeliveryAttemptId`를 만들고, 고정된 템플릿 버전과
reuses the pinned template version and rendered digest. Sending different content is a new 렌더링 digest를 다시 쓴다. 다른 내용을 보내는 것은 redrive가 아니라 새 알림이다. 모호한 attempt를 redrive하려면 중복
notification, not a redrive. Redriving an ambiguous attempt requires explicit duplicate-risk approval, 위험 승인을 명시해야 한다. 첫 제출이 사용자에게 닿았는지 플랫폼이 정말로 알 수 없기 때문이다.
because the platform genuinely cannot tell whether the first submission reached the user.
## Actuator surface ## actuator 표면
Provider runtime states and generations, queue depth and age, callback and reconciliation health. provider 런타임 상태와 세대, 큐 깊이와 나이, 콜백과 맞추기 상태. 주소와 자격 증명은 절대 싣지 않는다.
Never addresses, never credentials.
+19 -19
View File
@@ -1,34 +1,34 @@
# Provider runbooks # provider runbook
## SMTP ## SMTP
| Symptom | Classification | Action | | 증상 | 분류 | 조치 |
|---|---|---| |---|---|---|
| Final `2xx` after `DATA` | `CONFIRMED_ACCEPTED` / `PROVIDER_ACCEPTED` | None; this is acceptance, not inbox delivery | | `DATA` 뒤 최종 `2xx` | `CONFIRMED_ACCEPTED` / `PROVIDER_ACCEPTED` | 없음. 받은편지함 도착이 아니라 수락이다 |
| `4yz` | `TRANSIENT_PROVIDER` | Retry under budget and deadline | | `4yz` | `TRANSIENT_PROVIDER` | 예산과 마감 안에서 다시 시도한다 |
| `5yz` | `PERMANENT_PROVIDER` or `INVALID_RECIPIENT` | Stop, or invalidate the contact point | | `5yz` | `PERMANENT_PROVIDER` 또는 `INVALID_RECIPIENT` | 멈추거나, 연락처를 무효로 한다 |
| Connection lost after `DATA` | `AMBIGUOUS_SUBMISSION` | Reconcile or escalate; do not resend automatically | | `DATA` 뒤 연결 끊김 | `AMBIGUOUS_SUBMISSION` | 맞추거나 넘긴다. 자동으로 다시 보내지 않는다 |
Connection, read, write and pool-acquire timeouts are all finite. There is no unbounded timeout. 연결, 읽기, 쓰기, 풀 획득 시간 상한은 모두 유한하다. 상한 없는 시간 상한은 없다.
## Amazon SES ## Amazon SES
`MessageId` is acceptance evidence. SES itself documents that it can accept a request and then not `MessageId`는 수락 증거다. SES 자신이 요청을 수락한 뒤 보내지 않을 수 있다고 문서에 적으므로, `MessageId`는 절대
send, so `MessageId` is never mapped to `DELIVERED`. `DELIVERED`로 매핑하지 않는다.
| Event | Normalized | | 이벤트 | 정규화 |
|---|---| |---|---|
| `Send` | reinforces `PROVIDER_ACCEPTED` | | `Send` | `PROVIDER_ACCEPTED`를 보강한다 |
| `Delivery` | `DELIVERY_CONFIRMED` / `NETWORK_OR_CARRIER_ACCEPTED` | | `Delivery` | `DELIVERY_CONFIRMED` / `NETWORK_OR_CARRIER_ACCEPTED` |
| `DeliveryDelay` | delay fact | | `DeliveryDelay` | 지연 사실 |
| `Bounce` (permanent) | `BOUNCED_HARD` plus hard-bounce suppression | | `Bounce` (permanent) | `BOUNCED_HARD`와 hard bounce 억제 |
| `Bounce` (transient) | `BOUNCED_SOFT`; retry policy input, not a suppression reason | | `Bounce` (transient) | `BOUNCED_SOFT`. 억제 사유가 아니라 재시도 정책의 입력이다 |
| `Complaint` | complaint fact plus suppression | | `Complaint` | complaint 사실과 억제 |
| `Reject` | `PROVIDER_REJECTED` | | `Reject` | `PROVIDER_REJECTED` |
| `RenderingFailure` | `TEMPLATE_FAILURE` | | `RenderingFailure` | `TEMPLATE_FAILURE` |
## Removed provider families ## 지운 provider family
Twilio, FCM, APNs, Web Push and Webhook adapters were removed because nothing assembled them; their Twilio, FCM, APNs, Web Push, Webhook 어댑터는 아무것도 조립하지 않아서 지웠고, 그 runbook도 함께 지웠다. 둘을 모두
runbooks went with them. The last commit that had both is named in `docs/capability-status.md` 가진 마지막 커밋은 `docs/capability-status.md`(제거된 코드)에 있다. 이 provider 중 하나를 다시 더하는 배포는 그 runbook을
(제거된 코드). A deployment that adds one of these providers back writes its runbook here with it. 여기에 함께 쓴다.

Some files were not shown because too many files have changed in this diff Show More