Merge remote-tracking branch 'origin/claude/t1-backend-layout-46973e' into claude/i1-layout-docs-merge-217f1e

This commit is contained in:
DongHyeonka
2026-11-07 14:59:07 +09:00
1330 changed files with 1947 additions and 25774 deletions
+25 -27
View File
@@ -57,20 +57,10 @@ jobs:
run: ./gradlew :verifyStrictLaneStages --dry-run --stacktrace
- name: Verify Compose profile contracts render exactly as declared
run: bash scripts/verify-compose-profile-contracts.sh
sample-portfolio:
# The sample is excluded from production architecture/runtime membership policy, but it is still
# the reference implementation adopters copy. Compile/test/OpenAPI drift must therefore block PRs.
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
# `qualityCheck` too: the root one covers the production leaves only, so the sample — the code
# adopters copy first — was analysed by no stage, and its SpotBugs exclusions matched nothing
# (review 2026-11-03 RR-06-05).
- name: Verify the standalone sample application
working-directory: src
run: ./gradlew :sample-portfolio:check :sample-portfolio:qualityCheck --stacktrace
# The repository root and src/ hold only the entries on the allow list (owner decision
# 2026-11-07): a new top-level folder is a decision, not a side effect of a feature commit.
- name: Refuse a top-level folder outside the allow list
run: python3 scripts/check-repo-layout.py
optional-platforms:
runs-on: ubuntu-latest
@@ -79,15 +69,15 @@ jobs:
- uses: ./.github/actions/setup-gradle-java
- name: Verify the optional gRPC platform build
working-directory: src
run: ./gradlew -p optional-platforms ci --stacktrace
run: ./gradlew -p platforms/optional-build ci --stacktrace
# The optional build's own lane-reachability check: the main build's cannot see these lanes
# (review 2026-11-03 RR-06-03).
- name: Require every optional-platform strict lane to be in an executed stage
working-directory: src
run: ./gradlew -p optional-platforms :verifyStrictLaneStages --dry-run --stacktrace
run: ./gradlew -p platforms/optional-build :verifyStrictLaneStages --dry-run --stacktrace
# gRPC schema policy (owner decision 18). protoc compiles src/grpc/grpc-contract inside the
# optional-platforms build above; lint and breaking-change policy belong to Buf, configured by
# gRPC schema policy (owner decision 18). protoc compiles src/platforms/grpc/grpc-contract inside
# the optional-platforms build above; lint and breaking-change policy belong to Buf, configured by
# buf.yaml next to the schema. Buf is a native binary rather than a Maven artifact, so it runs here
# and not inside Gradle — and nothing in the repository re-implements its rules.
grpc-proto-buf:
@@ -102,28 +92,38 @@ jobs:
version: 1.73.0
setup_only: true
- name: Lint the gRPC schema
working-directory: src/grpc/grpc-contract
working-directory: src/platforms/grpc/grpc-contract
run: buf lint
- name: Refuse a breaking change to the gRPC schema
working-directory: src/grpc/grpc-contract
working-directory: src/platforms/grpc/grpc-contract
env:
# Pull request: the target branch. Push: the commit this push replaced.
BASELINE: ${{ github.event_name == 'pull_request' && format('origin/{0}', github.base_ref) || github.event.before }}
run: |
set -euo pipefail
baseline_commit="$(git rev-parse --verify --quiet "${BASELINE}^{commit}" || true)"
if [[ -z "${baseline_commit}" ]] \
|| ! git cat-file -e "${baseline_commit}:src/grpc/grpc-contract/buf.yaml" 2>/dev/null; then
# The module moved from src/grpc to src/platforms/grpc on 2026-11-07. A baseline from
# before the move holds it at the old path, and comparing against that path keeps the
# breaking check running across the move instead of skipping it once.
baseline_dir=""
if [[ -n "${baseline_commit}" ]]; then
for candidate in src/platforms/grpc/grpc-contract src/grpc/grpc-contract; do
if git cat-file -e "${baseline_commit}:${candidate}/buf.yaml" 2>/dev/null; then
baseline_dir="${candidate}"
break
fi
done
fi
if [[ -z "${baseline_dir}" ]]; then
# The first change that introduces the module has nothing to be compatible with.
echo "::notice::grpc-proto-buf: baseline ${BASELINE} has no src/grpc/grpc-contract/buf.yaml; breaking check skipped."
echo "::notice::grpc-proto-buf: baseline ${BASELINE} has no grpc-contract/buf.yaml; breaking check skipped."
exit 0
fi
buf breaking --against "../../../.git#ref=${baseline_commit},subdir=src/grpc/grpc-contract"
buf breaking --against "../../../../.git#ref=${baseline_commit},subdir=${baseline_dir}"
release-gate:
needs:
- quality-gates
- sample-portfolio
- optional-platforms
- grpc-proto-buf
if: always()
@@ -134,14 +134,12 @@ jobs:
- name: Require every current blocking job to succeed
env:
QUALITY_RESULT: ${{ needs.quality-gates.result }}
SAMPLE_RESULT: ${{ needs.sample-portfolio.result }}
OPTIONAL_PLATFORMS_RESULT: ${{ needs.optional-platforms.result }}
GRPC_PROTO_BUF_RESULT: ${{ needs.grpc-proto-buf.result }}
run: |
set -euo pipefail
for result in \
"${QUALITY_RESULT}" \
"${SAMPLE_RESULT}" \
"${OPTIONAL_PLATFORMS_RESULT}" \
"${GRPC_PROTO_BUF_RESULT}"; do
if [[ "${result}" != "success" ]]; then
+2 -2
View File
@@ -26,7 +26,7 @@ jobs:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Start the NFSv4 certification environment
run: docker compose -f infra/fileserver/nfs/compose.yml up -d --wait
run: docker compose -f src/adapter/outbound/fileserver/compose/nfs/compose.yml up -d --wait
- name: Run the network-filesystem ambiguity suite
working-directory: src
run: >-
@@ -35,7 +35,7 @@ jobs:
--stacktrace
- name: Tear down the NFS environment
if: always()
run: docker compose -f infra/fileserver/nfs/compose.yml down -v
run: docker compose -f src/adapter/outbound/fileserver/compose/nfs/compose.yml down -v
fileserver-process-kill-matrix:
runs-on: ubuntu-latest
+2 -4
View File
@@ -24,10 +24,8 @@ on:
- 'src/.env'
- 'docs/registries/env-keys.yaml'
- 'src/Dockerfile'
- 'docker-compose.yml'
- 'infra/fileserver/nginx/**'
- 'infra/fileserver/kubernetes/**'
- 'infra/fileserver/nfs/**'
- 'compose.yaml'
- 'src/app-bootstrap/compose-lanes/fileserver.yaml'
- '.github/workflows/fileserver-pr.yml'
# Every Gradle job here installs its toolchain through this composite action, so a change to
# it changes what this gate runs.
+6 -6
View File
@@ -60,7 +60,7 @@ concurrency:
jobs:
# The main-branch stage of the Gradle gates (`:mainCheck`): the environment contract, full-boot
# qualification, the sample web contract, the public-path baseline, the conditional transport
# qualification, the public-path baseline, the conditional transport
# lanes, the messaging contract lanes and each leaf's document-contract lanes. API surfaces are
# in the pull-request `check` (owner decision 20). The rest left the pull-request gate (review
# 2026-09-24 BUILD, item 12); none of them is deleted.
@@ -207,7 +207,7 @@ jobs:
- name: Run every optional-platform performance-category strict lane
if: always()
working-directory: src
run: ./gradlew -p optional-platforms performanceCheck --continue --stacktrace
run: ./gradlew -p platforms/optional-build performanceCheck --continue --stacktrace
- name: Publish the performance lane reports
if: always()
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2
@@ -234,7 +234,7 @@ jobs:
# `grpc-operation-ledger-jpa:integrationTest`, which certifies the atomic
# `INSERT ... ON CONFLICT DO NOTHING` claim that durable mutation idempotency rests on against a
# real PostgreSQL. It was registered in Gradle, listed in `strictTestLanes`, and invoked by
# nothing: `-p optional-platforms ci` reaches `checkAll`, `qualityCheck` and the dependency
# nothing: `-p platforms/optional-build ci` reaches `checkAll`, `qualityCheck` and the dependency
# verifier, none of which runs a lane whose category is INTEGRATION, and release.yml's gRPC gate
# names only the three grpc-testkit lanes.
#
@@ -250,13 +250,13 @@ jobs:
- uses: ./.github/actions/setup-gradle-java
- name: Certify the gRPC operation ledger against real PostgreSQL
working-directory: src
run: ./gradlew -p optional-platforms integrationCheck --stacktrace
run: ./gradlew -p platforms/optional-build integrationCheck --stacktrace
- name: Publish the optional-platform lane reports
if: always()
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2
with:
name: grpc-optional-platform-integration-reports
path: src/optional-platforms/**/build/reports/tests/
path: src/platforms/grpc*/**/build/reports/tests/
if-no-files-found: warn
# Dynamic half of the compose-profile contract. Every blocking lane the matrix declares runs on
@@ -272,7 +272,7 @@ jobs:
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- name: Run every blocking Compose runtime lane
run: bash scripts/run-compose-runtime-smoke.sh --matrix src/config/runtime/compose-profile-contracts.json
run: bash scripts/run-compose-runtime-smoke.sh --matrix src/app-bootstrap/compose-lanes/compose-profile-contracts.json
- name: Publish sanitized runtime-smoke evidence
if: always()
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2
@@ -15,7 +15,7 @@ name: messaging-certification
on:
pull_request:
paths:
- "src/messaging/**"
- "src/platforms/messaging/**"
- ".github/workflows/messaging-certification.yml"
# Every Gradle job here installs its toolchain through this composite action, so a change to
# it changes what this gate runs.
@@ -47,5 +47,5 @@ jobs:
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2
with:
name: messaging-broker-certification-evidence
path: src/messaging/messaging-kafka/build/messaging-certification/
path: src/platforms/messaging/messaging-kafka/build/messaging-certification/
if-no-files-found: warn
+1 -1
View File
@@ -30,7 +30,7 @@ on:
- 'src/config/architecture/modules.json'
- 'src/.env'
- 'docs/notification/**'
- 'infra/notification/**'
- 'src/app-bootstrap/compose-lanes/smoke/notification-smoke.sh'
- '.github/workflows/notification-platform.yml'
# Every Gradle job here installs its toolchain through this composite action, so a change to
# it changes what this gate runs.
-1
View File
@@ -123,7 +123,6 @@ jobs:
'^src/config/architecture/modules\.json$' \
'^docs/jpa/' \
'^docs/adr/ADR-JPA-' \
'^infra/jpa/' \
"${common}"
# The servlet system contract on both containers the template supports (Tomcat, Jetty). Real
+5 -5
View File
@@ -1,6 +1,6 @@
# Redis SDK topology evidence.
#
# The lanes in infra/redis-sdk answer what the deterministic in-memory gateway cannot — Sentinel
# The lanes in src/adapter/outbound/redis-sdk/compose answer what the deterministic in-memory gateway cannot — Sentinel
# promotion behaviour, Cluster redirects, ACL coverage. docs/redis/support-matrix.md records which
# lane produced which evidence, and RedisSupportMatrixTest refuses an evidence claim that does not
# name the test class behind it.
@@ -34,7 +34,7 @@ on:
- "src/adapter/outbound/redis-runtime/**"
- "src/adapter/outbound/redis-sdk/**"
- "src/adapter/outbound/cache-redis/**"
- "infra/redis-sdk/**"
- "compose/redis/**"
- ".github/workflows/redis-sdk-topology.yml"
# Every Gradle job here installs its toolchain through this composite action, so a change to
# it changes what this gate runs.
@@ -122,7 +122,7 @@ jobs:
- name: Start the topology
env:
REDIS_VERSION: ${{ matrix.redis_version }}
run: docker compose -f "infra/redis-sdk/${{ matrix.topology }}/compose.yml" up -d --wait
run: docker compose -f "src/adapter/outbound/redis-sdk/compose/${{ matrix.topology }}/compose.yml" up -d --wait
- name: Record the image digest
id: image
run: |
@@ -161,7 +161,7 @@ jobs:
# however loudly the file is named "test".
tls)
port=6390
docker compose -f ../infra/redis-sdk/tls/compose.yml cp redis:/tls/ca.crt "$RUNNER_TEMP/redis-lane-ca.pem"
docker compose -f adapter/outbound/redis-sdk/compose/tls/compose.yml cp redis:/tls/ca.crt "$RUNNER_TEMP/redis-lane-ca.pem"
extra="-Predis.topology.trust-material=$RUNNER_TEMP/redis-lane-ca.pem"
tasks="$runtime"
;;
@@ -199,4 +199,4 @@ jobs:
retention-days: 90
- name: Stop the topology
if: always()
run: docker compose -f "infra/redis-sdk/${{ matrix.topology }}/compose.yml" down -v
run: docker compose -f "src/adapter/outbound/redis-sdk/compose/${{ matrix.topology }}/compose.yml" down -v
+5 -27
View File
@@ -132,7 +132,7 @@ jobs:
- uses: ./.github/actions/setup-gradle-java
- name: Run the gRPC Stable certification lanes
working-directory: src
run: ./gradlew -p optional-platforms releaseCheck --stacktrace
run: ./gradlew -p platforms/optional-build releaseCheck --stacktrace
# The operation ledger's real-PostgreSQL lane ran only on main and nightly
# (integration-main.yml), so a tag could be cut from a main whose ledger lane was red. It needs
# Docker, which a release runner has (review 2026-11-01 03-12).
@@ -140,15 +140,15 @@ jobs:
working-directory: src
env:
TESTCONTAINERS_REUSE_ENABLE: "false"
run: ./gradlew -p optional-platforms integrationCheck --stacktrace
run: ./gradlew -p platforms/optional-build integrationCheck --stacktrace
- name: Publish the gRPC release evidence
if: always()
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2
with:
name: grpc-release-evidence
path: |
src/grpc/grpc-testkit/build/reports/tests/
src/grpc/grpc-operation-ledger-jpa/build/reports/tests/
src/platforms/grpc/grpc-testkit/build/reports/tests/
src/platforms/grpc/grpc-operation-ledger-jpa/build/reports/tests/
if-no-files-found: warn
# Each gate runs as its own single-line `./gradlew <task>` step so that a failure names the gate
@@ -194,7 +194,7 @@ jobs:
# docs/jpa/support-matrix.md recorded all three as covered. start() now fails closed on a
# multi-version selection, so this matrix is the only way the Stable majors get covered.
#
# config/jpa/release-registry.json is the gate-task source: jpaReleaseQualification (persistence-jpa
# persistence-jpa release/release-registry.json is the gate-task source: jpaReleaseQualification (persistence-jpa
# build.gradle) depends on its blocking gates, so a gate naming a missing task fails when the task
# graph is built, and JpaReleaseRenderingTest holds this matrix and the promotion list below to the
# registry's Stable majors. Editing one without the other fails the persistence-jpa unit lane.
@@ -326,27 +326,6 @@ jobs:
:composition:fileserver-platform:test --tests '*FileserverDocumentationCoverageTest'
--stacktrace
fileserver-pvc-certification:
runs-on: ubuntu-latest
timeout-minutes: 45
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
# This job checks the manifest, and only the manifest; it applies nothing to a cluster. The
# cluster result comes from an operator running infra/fileserver/kubernetes/
# pvc-certification-job.yaml and recording it in docs/fileserver/storage-certification.md,
# where the absence of a cluster result is stated rather than hidden behind a green check.
- name: Check the certification manifest still says what the claim depends on
run: |
set -euo pipefail
manifest=infra/fileserver/kubernetes/pvc-certification-job.yaml
test -f "$manifest"
grep -q 'kind: PersistentVolumeClaim' "$manifest"
grep -q 'kind: Job' "$manifest"
# ReadWriteMany is explicitly not claimed; a manifest that quietly widened the access
# mode would certify a topology the support matrix says is uncertified.
grep -q 'ReadWriteOnce' "$manifest"
! grep -q 'ReadWriteMany' "$manifest"
fileserver-sensitive-telemetry-scan:
runs-on: ubuntu-latest
timeout-minutes: 20
@@ -372,7 +351,6 @@ jobs:
- jpa-registry-and-docs
- fileserver-full-verification
- fileserver-documentation-gate
- fileserver-pvc-certification
- fileserver-sensitive-telemetry-scan
# Job-level, because a job that declares `permissions:` replaces the workflow set entirely: this
# job and app-image-signing are the only ones that write anything anywhere, and
+8 -11
View File
@@ -4,7 +4,7 @@
이 저장소는 단순한 예제 블로그 애플리케이션이 아니라, Java 21 + 버전 카탈로그에 고정된 Spring Boot 4.x + Gradle 멀티모듈 기반의 Clean Architecture 템플릿이다.
기본 패키지는 `dev.caskeleton`이며, 예시 도메인은 production 모듈이 아니라 `sample-portfolio` 모듈(WorkLog 엔지니어링 작업 기록 게시판)에 격리한다. 새 프로젝트를 시작할 때는 도메인 이름, 패키지, 엔티티, 유스케이스를 교체할 수 있지만, 모듈 경계와 의존성 방향은 유지해야 한다.
기본 패키지는 `dev.caskeleton`이다. 업무 기능의 예시는 `scripts/new-feature.sh`의 출력과 `docs/manual/`이다. 새 프로젝트를 시작할 때는 도메인 이름, 패키지, 엔티티, 유스케이스를 교체할 수 있지만, 모듈 경계와 의존성 방향은 유지해야 한다.
## Prime Directive
@@ -85,8 +85,8 @@ root `CLAUDE.md`는 작업을 시작할 때 읽는 지도이고, 이 목록을
- `src/build.gradle`: 루트 라이프사이클(`ci`, `mainCheck`, `integrationCheck`, `performanceCheck`,
`releaseCheck`, `qualityCheck`, `configContractCheck`)과 버전/리비전. `verifyStrictLaneStages
--dry-run`(PR 게이트)은 그 빌드에서 `explicitOnly`가 아닌 strict lane이 workflow가 실제로 실행하는
단계(main 빌드: `ci`·`sample-portfolio:check`·`mainCheck`·`integrationCheck`·`performanceCheck`·
`releaseCheck`, optional-platforms 빌드: `-p optional-platforms`로 부르는 `ci`·`integrationCheck`·
단계(main 빌드: `ci`·`mainCheck`·`integrationCheck`·`performanceCheck`·
`releaseCheck`, optional-platforms 빌드: `-p platforms/optional-build`로 부르는 `ci`·`integrationCheck`·
`performanceCheck`·`releaseCheck`) 중 하나에 들어 있는지, 그리고 workflow의 접힌(`>`) run 블록이 빈
줄 때문에 옵션을 별개 명령으로 떼어 내지 않는지 검사한다. 두 빌드가 각자 검사를 돌린다. `-x`로 뺀
lane(Gradle처럼 축약 이름도 맞춰 본다)은 덮이지 않는다. Gradle이 작업을 돌리지 않는 명령(`--dry-run`·
@@ -148,7 +148,6 @@ commit 정책은 모든 플랫폼에서 `human-only`이며 agent는 stage/commit
file server, HTTP client, identifier 능력을 port 뒤에서 구현한다. adapter 간 허용 edge는
registry만 따른다.
- `shared-contract`: skeleton-wide 운영 계약. business/domain 개념 저장 금지.
- `sample-portfolio`: 샘플/fixture consumer. production leaf가 의존하면 안 된다.
- `app-bootstrap`: Spring Boot entrypoint와 composition root. 비즈니스 유스케이스 금지.
## 의존성 방향
@@ -159,7 +158,6 @@ family 수준 기본 방향:
app-bootstrap -> adapter:inbound:* -> application-core -> domain-core
app-bootstrap -> adapter:outbound:* -> application-core -> domain-core
runtime modules -> shared-contract
sample-portfolio -> registered runtime leaves (fixture consumer only)
```
개별 edge는 `src/config/architecture/modules.json`의 `allowed_dependencies`가 유일한 목록이다.
@@ -181,8 +179,7 @@ Gradle 의존성 검증도 같은 registry를 읽는다. root 문서나 기억
10. focused test를 먼저 돌리고, 가능한 경우 전체 Gradle test를 돌린다.
단계별 판단 지점(배치·저장 포트·트랜잭션·멱등성·오류·권한)은 `docs/manual/`, 뼈대는
`scripts/new-feature.sh <FeatureName>`이 계층 leaf에 만든다. `sample-portfolio`는 모든 계층을 한 leaf에
두는 지울 수 있는 샘플이라 배치 예시가 아니다. 실제 기능은 계층 leaf별로 나눈다.
`scripts/new-feature.sh <FeatureName>`이 계층 leaf에 만든다. 실제 기능은 계층 leaf별로 나눈다.
## 테스트 전략
@@ -232,10 +229,10 @@ cd src
./gradlew qualityCheck # SpotBugs + FindSecBugs (leaf check에는 없다)
./gradlew testQualityCheck # 같은 분석을 테스트 source set에(config/spotbugs/exclude-test.xml, main 단계·optional 빌드는 ci)
./gradlew ci # PR 게이트 = leaf check + architecture + quality
./gradlew mainCheck # main 단계 = env 계약·전체 기동(샘플 포함)·public path·전송/메시징 레인·leaf 문서 대조 레인·기능 생성 왕복(verifyFeatureScaffold)·테스트 코드 정적 분석(testQualityCheck)
./gradlew mainCheck # main 단계 = env 계약·전체 기동·public path·전송/메시징 레인·leaf 문서 대조 레인·기능 생성 왕복(verifyFeatureScaffold)·테스트 코드 정적 분석(testQualityCheck)
./gradlew integrationCheck # 실제 컨테이너 integration 레인 전체(main·nightly, Docker 필요)
./gradlew performanceCheck # 부하·종료·자원 한계 레인(main·nightly). 상한은 항상 단언, 끄면 실패
./gradlew verifyStrictLaneStages --dry-run # 이 빌드의 strict lane이 workflow가 실행하는 단계에 속하는지(optional 빌드는 -p optional-platforms로 따로)
./gradlew verifyStrictLaneStages --dry-run # 이 빌드의 strict lane이 workflow가 실행하는 단계에 속하는지(optional 빌드는 -p platforms/optional-build로 따로)
./gradlew verifyPublicPathSnapshot
./gradlew :app-bootstrap:verifyEnvKeys
```
@@ -304,10 +301,10 @@ Docker/runtime 규칙:
1. `src/settings.gradle`의 `rootProject.name`을 새 프로젝트명으로 바꾼다.
2. Java package `dev.caskeleton`을 새 organization/project package로 바꾼다.
gRPC 플랫폼을 쓰면 proto 조직 이름 `caskeleton`(`src/grpc/grpc-contract/src/main/proto/caskeleton/`의
gRPC 플랫폼을 쓰면 proto 조직 이름 `caskeleton`(`src/platforms/grpc/grpc-contract/src/main/proto/caskeleton/`의
디렉터리, 각 `.proto`의 `package`·`java_package`)도 함께 바꾸고 `buf lint`로 확인한다.
3. `CaSkeletonApplication` 이름을 새 애플리케이션 이름으로 바꾼다.
4. production 모듈에는 목표 도메인의 entity, repository port, use case, adapter만 추가하고, 예시 코드는 `sample-portfolio`에 격리한다.
4. production 모듈에는 목표 도메인의 entity, repository port, use case, adapter만 추가한다.
5. 모듈 이름과 경계는 유지한다.
6. Docker image/application 이름을 새 프로젝트 기준으로 수정한다.
7. `.env`, `.env.local`, `application.yml`의 예시 값을 새 런타임 요구사항에 맞춘다.
+4 -3
View File
@@ -54,12 +54,13 @@ brief(작업 지시문)가 있으면 brief의 범위·크기·완료 기준이
## 5. 코드만 보고는 헷갈리는 곳
- **최상위 폴더는 정해진 것만 둔다.** 저장소 루트는 `compose.yaml`(개발 환경)·`compose/`(그 보조 파일)·`docs/`·`scripts/`·`src/`(Gradle 루트)다. `src/` 아래는 계층 leaf 폴더, `composition/`(조립), `platforms/`(들여온 제품: `messaging`·`grpc`·`grpc-advanced`와 optional 빌드 `optional-build`), Gradle 루트 표준(`build-logic`·`gradle`·`config`)이다. 테스트 환경 파일은 그 lane을 가진 leaf 안에 둔다. `scripts/check-repo-layout.py`(PR 게이트)가 허용 목록 밖의 최상위 항목을 막는다.
- **leaf 목록은 registry 하나다.** 문서는 leaf 개수를 적지 않는다(적힌 수는 leaf가 늘면 틀린다). runtime membership 목록은 없다. 조립 루트가 받을 수 있는 모듈은 registry의 `allowed_dependencies`가 정하고, 방향 게이트가 그 밖의 edge를 막는다.
- **`src/messaging/*`는 Clean Architecture 계층이 아니다.** 자기 API·SPI·adapter·조립 경계를 가진, 들여온(vendored) 메시징 제품이다. `domain-core`·`application-core`·`shared-contract`에 의존하지 않는다. 이 애플리케이션은 `adapter:outbound:messaging`의 bridge로만 닿는다. 이유와 지역 규칙은 `src/messaging/CLAUDE.md`다.
- **`src/platforms/messaging/*`는 Clean Architecture 계층이 아니다.** 자기 API·SPI·adapter·조립 경계를 가진, 들여온(vendored) 메시징 제품이다. `domain-core`·`application-core`·`shared-contract`에 의존하지 않는다. 이 애플리케이션은 `adapter:outbound:messaging`의 bridge로만 닿는다. 이유와 지역 규칙은 `src/platforms/messaging/CLAUDE.md`다.
- **`composition:*` leaf는 조립만 한다.** outbox relay, 멱등성 executor, durable operation처럼 bootstrap에서 떼어 낸 조립이다. 각각 `runtimeOnly` 한 줄로 고른다.
- **capability는 한 줄로 켜고 끈다.** 기본 조립은 web inbound, 운영 관측, core들, support·identifier뿐이다. JPA도 `src/app-bootstrap/build.gradle`의 `runtimeOnly` 한 줄로 켠다. 규칙은 `AGENTS.md` 「부가 기능(capability) 모듈 규칙」이다.
- **gRPC 플랫폼 라이브러리는 다른 빌드다.** `src/grpc/*`·`src/grpc-advanced/*`(registry의 `"build": "optional-grpc"`)는 `-p optional-platforms`로 돈다. `adapter:inbound:grpc`는 애플리케이션 adapter라 주 빌드에 있다.
- **`src/sample-portfolio`는 지울 수 있는 샘플이다.** 한 leaf에 모든 계층을 둔 모양이라 배치를 따라 하지 않는다. 새 기능의 예시는 `scripts/new-feature.sh`의 출력이다.
- **gRPC 플랫폼 라이브러리는 다른 빌드다.** `src/platforms/grpc/*`·`src/platforms/grpc-advanced/*`(registry의 `"build": "optional-grpc"`)는 `-p platforms/optional-build`로 돈다. `adapter:inbound:grpc`는 애플리케이션 adapter라 주 빌드에 있다.
- **새 기능의 예시는 `scripts/new-feature.sh`의 출력이다.** 샘플 모듈은 2026-11-07에 지웠다. 기법 예시는 `docs/manual/`이 실제 코드(fileserver, durable operation)를 가리킨다.
- **성능 lane에는 단언을 끄는 스위치가 없다.** convention이 상한을 매번 단언하고, `performance.assertions.enabled`에 `true` 아닌 값이 들어오거나 skip이 있으면 테스트 전에 실패한다. 손으로 돌리든 workflow든 같다(`AGENTS.md` 「Gradle 정책 권위」).
- **저장소 파일을 읽는 테스트는 태그가 있다.** 문서와 대조하는 테스트는 `document-contract`(main 단계 `mainCheck`), 빌드 스크립트·workflow를 읽는 테스트는 `repository-contract`(PR)다. 문서를 고치면 그 문서를 읽는 테스트를 찾는다.
- **커밋 정책은 `human-only`다.** brief가 허용한 것만 자기 브랜치에 한다. 커밋과 push는 따로 허용된다. 자세한 것은 [docs/work/README.md](docs/work/README.md) 4절이다.
+11 -18
View File
@@ -1,6 +1,6 @@
# ca-skeleton — Clean Architecture Spring Boot 템플릿
ca-skeleton은 Java 21과 버전 카탈로그에 고정된 Spring Boot 4.x, Gradle 멀티모듈 기반의 Clean Architecture 백엔드 템플릿입니다. fork해서 도메인·패키지·엔티티·유스케이스만 교체하면 새 서비스를 시작할 수 있고, 모듈 경계와 의존 방향은 그대로 유지합니다. 기본 패키지는 `dev.caskeleton`이며, 예시 도메인은 production 모듈이 아니라 `sample-portfolio` 모듈(WorkLog 작업 기록 게시판)에 격리합니다.
ca-skeleton은 Java 21과 버전 카탈로그에 고정된 Spring Boot 4.x, Gradle 멀티모듈 기반의 Clean Architecture 백엔드 템플릿입니다. fork해서 도메인·패키지·엔티티·유스케이스만 교체하면 새 서비스를 시작할 수 있고, 모듈 경계와 의존 방향은 그대로 유지합니다. 기본 패키지는 `dev.caskeleton`입니다. 업무 기능의 예시는 생성 명령 `scripts/new-feature.sh`의 출력과 [docs/manual/](docs/manual/README.md)입니다.
이 문서는 전체 구조와 첫 실행만 다룹니다. 모듈별 상세 규칙과 설계 근거는 각 모듈의 README와 `CLAUDE.md`가, 빌드·환경 변수 상세는 [src/README.md](src/README.md)가 소유합니다.
@@ -12,7 +12,6 @@ ca-skeleton은 Java 21과 버전 카탈로그에 고정된 Spring Boot 4.x, Grad
app-bootstrap -> adapter:inbound:* -> application-core -> domain-core
app-bootstrap -> adapter:outbound:* -> application-core -> domain-core
모든 런타임 모듈 -> shared-contract
sample-portfolio -> 등록된 런타임 리프 (fixture 소비자 전용)
```
family 수준의 책임은 다음과 같습니다.
@@ -26,7 +25,6 @@ family 수준의 책임은 다음과 같습니다.
| `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 |
| `sample-portfolio` | WorkLog 예시 도메인(fixture/reference). production이 의존하지 않음 |
등록된 leaf 목록과 각 leaf의 Gradle path·소스 경로·허용 production 의존 edge는
[src/config/architecture/modules.json](src/config/architecture/modules.json)이 SSOT입니다. focused
@@ -38,10 +36,10 @@ test는 해당 Gradle path에서 `./gradlew <gradle-path>:test --console=plain`
전제조건은 Temurin 21(루트 [.tool-versions](.tool-versions)에 고정)과 Docker Engine 또는 Docker Desktop입니다. Gradle은 저장소 wrapper를 씁니다. 첫 실행 진입점은 하나입니다.
```bash
scripts/bootstrap-local.sh # 다른 Compose overlay는 scripts/bootstrap-local.sh <profile>
scripts/bootstrap-local.sh
```
`scripts/bootstrap-local.sh`는 compile 검사, PostgreSQL Compose 기동, 애플리케이션 이미지 build·기동, `GET /api/healthcheck` HTTP smoke를 순서대로 실행합니다. 각 단계가 `bootstrap N/4` 줄을 찍고 실패하면 그 단계에서 멈추므로 실패 단계가 드러납니다. 기동을 확인하려면 health endpoint를 호출합니다.
`scripts/bootstrap-local.sh`는 compile 검사, PostgreSQL Compose 기동, 애플리케이션 이미지 build·기동, `GET /api/healthcheck` HTTP smoke를 순서대로 실행합니다. 쓰는 compose 파일은 저장소 루트의 `compose.yaml` 하나입니다. 각 단계가 `bootstrap N/4` 줄을 찍고 실패하면 그 단계에서 멈추므로 실패 단계가 드러납니다. 기동을 확인하려면 health endpoint를 호출합니다.
```bash
curl -fsS http://localhost:8080/api/healthcheck
@@ -50,9 +48,13 @@ curl -fsS http://localhost:8080/api/healthcheck
로컬 스택을 내릴 때는 저장소 루트에서 실행합니다.
```bash
docker compose -f docker-compose.yml -f docker-compose.local.yml down
docker compose --profile '*' down
```
`--profile '*'`가 없으면 profile이 달린 `db`가 남습니다. compose는 켜진 profile의 서비스만 내립니다.
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)에 있습니다.
### 기본 조립과 부가 기능
@@ -91,10 +93,10 @@ H2 실행은 wiring과 애플리케이션 동작만 검증하고, migration과 v
애플리케이션 이름 등 나머지 rename 단계는 위 체크리스트를 따릅니다.
3. `CaSkeletonApplication`을 새 애플리케이션 이름으로 바꾸고, 목표 도메인의 엔티티·repository port·유스케이스·adapter를 production 모듈에 추가합니다. 예시 코드는 `sample-portfolio`에만 둡니다.
3. `CaSkeletonApplication`을 새 애플리케이션 이름으로 바꾸고, 목표 도메인의 엔티티·repository port·유스케이스·adapter를 production 모듈에 추가합니다. 새 업무 기능은 `scripts/new-feature.sh <FeatureName>`으로 만듭니다.
4. 모듈 이름과 경계는 그대로 유지합니다.
검증은 먼저 composition root의 빠른 테스트와 sample-off 계약을 확인합니다. 루트에서
검증은 먼저 composition root의 빠른 테스트와 아키텍처 검사를 확인합니다. 루트에서
`./gradlew test`를 호출하면 등록된 모든 하위 프로젝트의 `test`를 실행하므로 일상적인 로컬
피드백 명령으로 사용하지 않습니다. 저장소 전체 qualification은 CI 또는 명시적인 `ci` task가
담당합니다.
@@ -102,14 +104,11 @@ H2 실행은 wiring과 애플리케이션 동작만 검증하고, migration과 v
```bash
cd src
./gradlew :app-bootstrap:test
./gradlew :sample-portfolio:check
./gradlew architectureCheck
```
병합 전 저장소 전체 검증이 필요하면 `./gradlew ci`를 실행합니다.
`sample-portfolio`는 템플릿이 유지하는 fixture/reference 모듈이라 production 모듈이 의존하지 않고, runtime에 sample bean이나 endpoint를 넣지 않습니다. 다운스트림 fork에서 fixture가 더 필요 없을 때만 sample-off 테스트를 통과시킨 뒤 정리합니다.
## 아키텍처 규칙과 검증
애플리케이션이 동작하더라도 아래를 어기면 병합하지 않습니다. HARD-STOP 7개 조건의 정본 로컬
@@ -135,8 +134,7 @@ cd src
## 수동 전용 Gradle 태스크
아래 세 태스크는 **어떤 워크플로도 실행하지 않으며, 그게 의도다.** 자동 실행이 틀린 이유를 각각
적어 둔다.
아래 태스크는 **어떤 워크플로도 실행하지 않으며, 그게 의도다.** 자동 실행이 틀린 이유를 적어 둔다.
여기 적힌 태스크 이름이 실재하는지 검사하던 `verifyReadmeCommands`는 삭제했다. 그건 이 문서의
```bash 블록을 직접 파싱해 `./gradlew`·`docker compose`·`make` 토큰을 실제 태스크 그래프와 대조하는
@@ -146,16 +144,11 @@ Markdown 명령 파서였고, 그 결과 "README에 무엇을 쓸 수 있는가"
```bash
cd src
./gradlew :grpc:grpc-testkit:grpcPerformanceTest
./gradlew :sample-portfolio:openapiCheckSnapshot -PapproveOpenApiChange
```
- `grpcPerformanceTest` — latency percentile·saturation·drain budget을 **측정**한다. 공유 CI
runner의 측정값은 흔들리고, 흔들리는 게이트는 결국 꺼진다. leaf `build.gradle`이 이 태스크의
태그를 `test`에서 제외하는 이유도 같다. 성능 회귀가 의심될 때 사람이 이름으로 부른다.
- `openapiCheckSnapshot` — 드리프트 검사 자체는 이미 자동으로 돈다. 이 태스크가 감싸는
`OpenApiDriftContractTest`는 `:sample-portfolio:test`의 일부이고, 그건 `check` 안이며 stage 1에서
실행된다. 이 태스크의 고유한 역할은 `-PapproveOpenApiChange`로 **커밋된 스냅샷을 다시 만드는 것**
— 의도된 API 변경을 사람이 승인하는 지점이다. 자동으로 돌리면 승인이 승인이 아니게 된다.
## 더 알아보기
+426
View File
@@ -0,0 +1,426 @@
# =============================================================================
# 개발 환경 — 이 repo의 compose 파일은 이것 하나다.
#
# docker compose up -d --wait app # 앱 컨테이너(기본 조립, local 런타임)
# docker compose up -d --wait db # 뒷단 서비스 하나만(이름을 대면 그 profile이 켜진다)
# docker compose --profile jpa --profile redis up -d --wait # 뒷단 서비스 묶음
# docker compose --profile '*' down # 내린다. 데이터까지 지우려면 down -v
#
# 내릴 때 --profile '*'를 붙인다. 붙이지 않으면 compose는 켜진 profile의 서비스만 내리므로, 이름으로
# 띄운 db 같은 profile 서비스가 남는다.
#
# 뒷단 서비스는 capability 이름의 profile로 고른다. profile을 대지 않으면 app만 뜬다.
#
# profile 서비스 쓰는 기능
# jpa db (PostgreSQL 16) JPA
# redis redis (ACL 계정) Redis
# kafka kafka Kafka 발행
# mongo mongo, mongo-rs-init MongoDB
# objectstorage minio, minio-init 객체 저장소
# auth keycloak JWT 발급자
# mail mailpit (STARTTLS 필수) SMTP 발송
#
# 이 파일이 마운트하는 보조 파일은 compose/ 아래에 있다. compose lane(테스트)은 이 파일을 바탕으로
# 쓰고, lane에만 필요한 overlay·smoke client·스키마 적용은 src/app-bootstrap/compose-lanes/에 있다.
# 경로는 모두 이 파일이 있는 저장소 루트 기준이다.
#
# auth profile은 keycloak client secret 파일이 있어야 뜬다. lane은 실행마다 만들고 지운다. 손으로 띄울
# 때는 compose/keycloak/secrets/graphql-smoke-client-secret에 아무 값이나 한 줄 넣는다(그 폴더는
# Git이 무시한다). mail profile도 같다: compose/mailpit/tls/에 server.crt·server.key가 있어야 한다.
#
# Graceful-shutdown sync table (feature-container-runtime-contract D5):
# App shutdown timeout : 30s (APP_SERVER_SHUTDOWN_TIMEOUT — SSOT: docs/registries/
# env-keys.yaml, owner feature-env-driven-runtime-configuration)
# Async executor wait : 19s (AsyncExecutorConfig.AWAIT_TERMINATION_SECONDS)
# Container preStop : 5s (handled by the orchestrator / stop_grace_period offset)
# stop_grace_period : 60s (30s app drain + 19s async + 5s preStop + 6s safety margin)
#
# The drain and the async wait are consecutive, not concurrent: Spring finishes the lifecycle
# phase (the web server's graceful drain) before it destroys the executor, which then waits for
# its queue. A 40s grace let the container be killed 9s into that wait (07-07).
# DeveloperExperienceContractTest fails when this value is below the sum.
#
# Memory limit (D4):
# The container memory limit MUST be set for -XX:MaxRAMPercentage=75 to be meaningful.
# Default 512m suits a small service; adjust per deployment. A compose lane that boots every
# capability at once raises it for itself (compose-profile-contracts.json, appMemoryLimit).
# =============================================================================
# The local MinIO runtime, used by the server below and by the lane's object storage smoke client.
#
# It is the image the MinIO qualification lanes measured, by the same digest:
# src/adapter/outbound/objectstorage/src/test/resources/object-storage/minio-provider-evidence.json
# records it with the conditional-write findings, and ComposeMinioImageMatchesEvidenceTest in that
# leaf fails when this default (or the lane file's copy) and the evidence disagree. Change them
# together.
#
# Source: pgsty/minio, a community fork on Docker Hub, after Docker Hub's minio/minio and quay.io
# stopped serving MinIO images (review 05-09). cgr.dev/chainguard/minio measured the same but was
# not chosen; the evidence file's rejectedCandidates says why. LOCAL_MINIO_IMAGE points this runtime
# at a mirror; the lanes take OBJECT_STORAGE_MINIO_IMAGE, digest-checked.
x-local-minio-image: &local-minio-image "${LOCAL_MINIO_IMAGE:-pgsty/minio@sha256:b6bfe7239bfc83fb90d31612d9704d86039dd714f7904b3f1ad68f211e602372}"
services:
app:
build:
context: src/
dockerfile: Dockerfile
args:
RELEASE_VERSION: "${RELEASE_VERSION:-0.0.1}"
BUILD_VERSION: "${BUILD_VERSION:-0.0.1+0000000}"
GIT_SHA: "${GIT_SHA:-0000000}"
SOURCE_URL: "${SOURCE_URL:-https://example.invalid/ca-tmpl}"
# default = the composition a service ships. scripts/run-compose-runtime-smoke.sh sets
# qualification: every capability module present, each lane switching on what it tests.
COMPOSITION: "${COMPOSITION:-default}"
# The composition is in the tag, so a lane's qualification image is never reused as the
# default one (Compose reuses a matching tag instead of building).
image: caskeleton:${BUILD_VERSION:-0.0.1_local_0000000}-${COMPOSITION:-default}
# Optional, because src/.env is operator input and a fresh clone does not have one. Before this
# was marked optional, untracking that file made `docker compose config` fail outright on a
# clone. The tracked contract is src/.env.example; copy it. A compose lane does not depend on it:
# its values go into a generated `environment:` block, which outranks every env_file.
env_file:
- path: ./src/.env
required: false
ports:
- "${APP_SERVER_PORT:-8080}:8080"
# Management (health, info, prometheus — answered without authentication) on loopback only:
# published on every interface it reaches the whole LAN (07-13). The smoke lanes read it from
# inside the container, so they need no host port at all.
- "127.0.0.1:9001:9001"
environment:
# Explicit, not inherited. A Compose profile selects services; it says nothing about which
# environment the application believes it is in. The dev and prod-smoke lane overlays set
# their own.
SPRING_PROFILES_ACTIVE: "local"
TZ: "UTC"
LANG: "C.UTF-8"
LC_ALL: "C.UTF-8"
# Graceful shutdown — fallback matches the env-keys.yaml SSOT default (30s).
# Override via .env or docker compose --env-file if you need a different value.
APP_SERVER_SHUTDOWN_TIMEOUT: "${APP_SERVER_SHUTDOWN_TIMEOUT:-30s}"
APP_SERVER_SHUTDOWN: "graceful"
# The `db` service below, on the internal network. The default composition does not read
# these; a service that selects the relational capability does.
APP_DATASOURCE_URL: "jdbc:postgresql://db:5432/${POSTGRES_DB:-ca_skeleton}"
APP_DATASOURCE_USERNAME: "${APP_DATASOURCE_USERNAME:-ca_skeleton}"
APP_DATASOURCE_PASSWORD: "${APP_DATASOURCE_PASSWORD:-ca_skeleton}"
# ---- Read-only root filesystem (D2) -------------------------------------
# The application must write only to the tmpfs mounts declared below.
# /tmp — Tomcat basedir (see -Dserver.tomcat.basedir=/tmp in Dockerfile).
# /var/tmp/heap — heap dump landing zone (see -XX:HeapDumpPath=/var/tmp/heap).
read_only: true
tmpfs:
- /tmp:mode=1777,size=128m
- /var/tmp/heap:mode=1777,size=512m
# No volume: the shipped composition keeps nothing on disk. A capability that does brings its
# mount in its own overlay, added with -f when the capability is selected, so this file never
# names one (07-08).
# ---- Memory limit (D4) --------------------------------------------------
# Must be set so -XX:MaxRAMPercentage=75 can compute a meaningful heap bound.
mem_limit: 512m
memswap_limit: 512m
# ---- Graceful shutdown (D5) ---------------------------------------------
# stop_grace_period = app drain (30s, env-keys SSOT) + async wait (19s) + preStop (5s)
# + margin (6s) = 60s.
stop_grace_period: 60s
# ---- Health check -------------------------------------------------------
# The actuator readiness probe on the management port (9001). It answers under every runtime
# (local, dev, prod), unlike the public health path, whose base path differs by runtime.
healthcheck:
test:
- "CMD"
- "wget"
- "--no-verbose"
- "--tries=1"
- "--spider"
- "http://localhost:9001/actuator/health/readiness"
interval: 5s
timeout: 3s
start_period: 60s
retries: 12
restart: unless-stopped
networks:
- caskeleton-infra
# ---- PostgreSQL --------------------------------------------------------------
# Published on the loopback interface only, so a host-side run (`./gradlew :app-bootstrap:bootRun`,
# IDE) reaches the same database the containerised app reaches over the internal network. The
# port is the one src/.env.example's APP_DATASOURCE_URL names.
db:
profiles:
- jpa
image: postgres:16-alpine
environment:
POSTGRES_DB: "${POSTGRES_DB:-ca_skeleton}"
POSTGRES_USER: "${APP_DATASOURCE_USERNAME:-ca_skeleton}"
POSTGRES_PASSWORD: "${APP_DATASOURCE_PASSWORD:-ca_skeleton}"
TZ: "UTC"
volumes:
- type: volume
source: caskeleton-db-data
target: /var/lib/postgresql/data
ports:
- "127.0.0.1:5433:5432"
networks:
- caskeleton-infra
healthcheck:
test:
[
"CMD-SHELL",
"pg_isready -U ${APP_DATASOURCE_USERNAME:-ca_skeleton} -d ${POSTGRES_DB:-ca_skeleton}",
]
interval: 10s
timeout: 5s
retries: 5
start_period: 30s
# ---- MongoDB -----------------------------------------------------------------
# A replica set of one. Single-node is still a replica set: transactions and change streams need
# one, and a standalone mongod that "works for reads" is a deployment that discovers the
# difference at the first transaction.
mongo:
profiles:
- mongo
image: mongo:8.0.16
command: ["mongod", "--replSet", "rs0", "--bind_ip_all"]
volumes:
- type: volume
source: caskeleton-mongo-data
target: /data/db
networks:
- caskeleton-infra
healthcheck:
test: ["CMD", "mongosh", "--quiet", "--eval", "db.adminCommand('ping').ok"]
interval: 10s
timeout: 5s
retries: 10
start_period: 20s
mongo-rs-init:
profiles:
- mongo
image: mongo:8.0.16
depends_on:
mongo:
condition: service_healthy
# Idempotent: rs.initiate() on an already-initiated set returns an error this swallows, so the
# stack can be re-run against a surviving volume without a manual reset.
command:
- mongosh
- --host
- mongo
- --quiet
- --eval
- >-
try { rs.initiate({_id:'rs0',members:[{_id:0,host:'mongo:27017'}]}) }
catch (e) { if (!/already initialized/i.test(e.message)) { throw e } }
networks:
- caskeleton-infra
restart: "no"
# ---- Kafka -------------------------------------------------------------------
kafka:
profiles:
- kafka
image: apache/kafka:3.8.0
environment:
KAFKA_NODE_ID: "1"
KAFKA_PROCESS_ROLES: "broker,controller"
KAFKA_LISTENERS: "PLAINTEXT://:9092,CONTROLLER://:9093"
KAFKA_ADVERTISED_LISTENERS: "PLAINTEXT://kafka:9092"
KAFKA_CONTROLLER_QUORUM_VOTERS: "1@kafka:9093"
KAFKA_CONTROLLER_LISTENER_NAMES: "CONTROLLER"
KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: "CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT"
KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: "1"
KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: "1"
KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: "1"
networks:
- caskeleton-infra
healthcheck:
test:
["CMD-SHELL", "/opt/kafka/bin/kafka-broker-api-versions.sh --bootstrap-server kafka:9092"]
interval: 10s
timeout: 10s
retries: 12
start_period: 30s
# ---- Redis -------------------------------------------------------------------
# Authenticated the way a deployment authenticates, with the lanes' test-fixture accounts:
# compose/redis/acl/lane-fixture-accounts.acl, the same file the Redis topology lanes use, mounted
# as it is rather than copied. It is not a deployment file — its passwords are public and it carries
# a lane-only `+@all` account (compose/redis/acl/README.md). Its first line turns the passwordless
# `default` user off, so the application connects as the named accounts the lane contract gives it
# (compose-profile-contracts.json, $redisComment).
#
# This Redis was open and the lanes declared app.redis.authentication.anonymous-access-accepted.
# The application then logged that trade, and the missing advanced account, as two startup
# warnings — correctly, because in production both are risks — and every Redis lane failed its
# "startup is silent" check. Quieting the warning would hide the same trade in production; the
# lane now authenticates the way a deployment does instead.
#
# The passwords are the file's fixture values (compose/redis/acl/README.md); this container is
# on the internal network only and publishes no port.
redis:
profiles:
- redis
image: redis:7.4
command:
- redis-server
- --appendonly
- "no"
- --save
- ""
- --aclfile
- /etc/redis/acl/lane-fixture-accounts.acl
volumes:
- type: bind
source: ./compose/redis/acl
target: /etc/redis/acl
read_only: true
networks:
- caskeleton-infra
healthcheck:
test:
# As the application account: with `default` off, an unauthenticated PING answers NOAUTH.
- "CMD-SHELL"
- "[ \"$$(redis-cli --user ca-skeleton-application --pass fixture-application --no-auth-warning ping)\" = PONG ]"
interval: 5s
timeout: 3s
retries: 12
start_period: 5s
# ---- Mailpit — the reference SMTP relay ----------------------------------------
mailpit:
profiles:
- mail
image: axllent/mailpit:v1.21
environment:
MP_SMTP_AUTH_ACCEPT_ANY: "1"
# MP_SMTP_AUTH_ALLOW_INSECURE is deliberately absent, and Mailpit refuses to start with both:
# "TLS cannot be required with --smtp-auth-allow-insecure". It existed to permit credentials
# over a plaintext connection, which is exactly what requiring STARTTLS removes the need for —
# any AUTH now happens inside the TLS session.
# STARTTLS, required. Not a hardening extra: SmtpProviderProperties.TlsMode has two members and
# neither is plaintext, so the platform cannot describe an unencrypted relay at all. A stack
# that wanted a plaintext Mailpit would be asking for a transport the type refuses to express,
# and the honest way to satisfy it is to give the relay a certificate.
MP_SMTP_TLS_CERT: /run/mailpit-tls/server.crt
MP_SMTP_TLS_KEY: /run/mailpit-tls/server.key
MP_SMTP_REQUIRE_STARTTLS: "true"
volumes:
# Generated per run by the qualification wrapper for the host name `mailpit`, and removed on
# teardown, exactly like the PostgreSQL lane certificate. A committed test certificate is a
# private key in Git.
- type: bind
source: ./compose/mailpit/tls
target: /run/mailpit-tls
read_only: true
networks:
- caskeleton-infra
healthcheck:
test: ["CMD", "/mailpit", "readyz"]
interval: 5s
timeout: 3s
retries: 12
start_period: 5s
# ---- MinIO -------------------------------------------------------------------
minio:
profiles:
- objectstorage
image: *local-minio-image
command: ["server", "/data"]
environment:
MINIO_ROOT_USER: "${MINIO_ROOT_USER:-caskeleton}"
MINIO_ROOT_PASSWORD: "${MINIO_ROOT_PASSWORD:-caskeleton-local}"
volumes:
- type: volume
source: caskeleton-minio-data
target: /data
networks:
- caskeleton-infra
healthcheck:
test: ["CMD", "mc", "ready", "local"]
interval: 10s
timeout: 5s
retries: 10
start_period: 10s
# Bucket and policy bootstrap. Not a substitute for the round trip: creating a bucket proves the
# server accepts an admin command, not that an object survives being written and read back.
minio-init:
profiles:
- objectstorage
# The client from the same supplier as the server. cgr.dev/chainguard/minio-client was not used:
# it has no shell, and the bootstrap below is a shell script.
image: "${LOCAL_MINIO_MC_IMAGE:-pgsty/mc@sha256:ce62c9053c69ce12a527a322345b5ad9f44b5f8a7b8189f82e516f2e3f30f1d8}"
depends_on:
minio:
condition: service_healthy
entrypoint: ["/bin/sh", "/opt/minio/bucket-bootstrap.sh"]
environment:
MINIO_ENDPOINT: "http://minio:9000"
MINIO_ROOT_USER: "${MINIO_ROOT_USER:-caskeleton}"
MINIO_ROOT_PASSWORD: "${MINIO_ROOT_PASSWORD:-caskeleton-local}"
MINIO_BUCKET: "${MINIO_BUCKET:-ca-skeleton-objects}"
volumes:
- type: bind
source: ./compose/minio/init
target: /opt/minio
read_only: true
networks:
- caskeleton-infra
restart: "no"
# ---- Keycloak ----------------------------------------------------------------
keycloak:
profiles:
- auth
image: quay.io/keycloak/keycloak:26.0
# The wrapper reads the client secret from a mounted file and execs kc.sh. The realm artifact
# carries only a ${...} reference, so no secret value is in Git, in the rendered config, or on a
# command line.
entrypoint: ["/bin/bash", "/opt/keycloak-entrypoint/entrypoint.sh"]
environment:
KC_BOOTSTRAP_ADMIN_USERNAME: "${KEYCLOAK_ADMIN:-admin}"
KC_BOOTSTRAP_ADMIN_PASSWORD: "${KEYCLOAK_ADMIN_PASSWORD:-admin}"
KC_HEALTH_ENABLED: "true"
volumes:
- type: bind
source: ./compose/keycloak/entrypoint.sh
target: /opt/keycloak-entrypoint/entrypoint.sh
read_only: true
- type: bind
source: ./compose/keycloak/realms
target: /opt/keycloak/data/import
read_only: true
secrets:
- keycloak-graphql-smoke-client-secret
networks:
- caskeleton-infra
healthcheck:
test:
- "CMD-SHELL"
- "exec 3<>/dev/tcp/127.0.0.1/9000 && echo -e 'GET /health/ready HTTP/1.1\\r\\nHost: localhost\\r\\nConnection: close\\r\\n\\r\\n' >&3 && cat <&3 | grep -q '\"status\": \"UP\"'"
interval: 10s
timeout: 5s
retries: 20
start_period: 30s
networks:
caskeleton-infra:
driver: bridge
volumes:
caskeleton-db-data:
driver: local
caskeleton-mongo-data:
driver: local
caskeleton-minio-data:
driver: local
secrets:
keycloak-graphql-smoke-client-secret:
file: ./compose/keycloak/secrets/graphql-smoke-client-secret
@@ -1,6 +1,6 @@
# Keycloak realm artifact
`realms/ca-skeleton-realm.json` is imported by the `keycloak` service in `docker-compose.infra.yml`
`realms/ca-skeleton-realm.json` is imported by the `keycloak` service in the root `compose.yaml`
and is the same realm every GraphQL qualification lane authenticates against.
## The client secret is a reference, never a value
@@ -42,9 +42,10 @@ a fork that copied one of them got an open account and a green lane.
## Who loads `lane-fixture-accounts.acl`
The Redis topology lanes (`../standalone`, `../sentinel`, `../cluster`, `../tls`) and the
The Redis topology lanes (`src/adapter/outbound/redis-sdk/compose/{standalone,sentinel,cluster,tls}`), the
application's Compose lanes that switch Redis on (`local-redis`, `all-adapters` in
`src/config/runtime/compose-profile-contracts.json`). Both mount this directory read-only; neither
`src/app-bootstrap/compose-lanes/compose-profile-contracts.json`), and the development stack's
`redis` service (root `compose.yaml`). They all mount this directory read-only; neither
keeps a copy, because a second copy of these lines is a second place for a password or a key
pattern to drift.
-579
View File
@@ -1,579 +0,0 @@
# =============================================================================
# Shared infrastructure, owned here and nowhere else.
#
# Environment overlays (local, dev, prod-smoke) describe how the application runs. This file
# describes what it runs against. Keeping the two apart is why `local` could stop meaning "the app
# plus a database" and start meaning "the app, with whichever services the lane asked for".
#
# Every service carries a Compose profile, so nothing here starts unless a lane names it. A profile
# selects services; it never implies a Spring profile. The lane definitions live in
# src/config/runtime/compose-profile-contracts.json, and scripts/verify-compose-profile-contracts.sh
# checks this file against them.
# =============================================================================
# The local MinIO runtime, used by the server and by the object-storage smoke client below.
#
# It is the image the MinIO qualification lanes measured, by the same digest:
# src/adapter/outbound/objectstorage/src/test/resources/object-storage/minio-provider-evidence.json
# records it with the conditional-write findings, and ComposeMinioImageMatchesEvidenceTest in that
# leaf fails when this default and the evidence disagree. Change both together.
#
# Source: pgsty/minio, a community fork on Docker Hub, after Docker Hub's minio/minio and quay.io
# stopped serving MinIO images (review 05-09). cgr.dev/chainguard/minio measured the same but was
# not chosen; the evidence file's rejectedCandidates says why. LOCAL_MINIO_IMAGE points this runtime
# at a mirror; the lanes take OBJECT_STORAGE_MINIO_IMAGE, digest-checked.
x-local-minio-image: &local-minio-image "${LOCAL_MINIO_IMAGE:-pgsty/minio@sha256:b6bfe7239bfc83fb90d31612d9704d86039dd714f7904b3f1ad68f211e602372}"
services:
# ---- PostgreSQL --------------------------------------------------------------
db:
profiles:
- local-jpa
- local-messaging-outbox
- local-fileserver
- local-notification-ingest
- local-notification-serving
- local-notification-handoff
- shared-infra
- prod-smoke
- all-adapters
image: postgres:16-alpine
environment:
POSTGRES_DB: "${POSTGRES_DB:-ca_skeleton}"
POSTGRES_USER: "${APP_DATASOURCE_USERNAME:-ca_skeleton}"
POSTGRES_PASSWORD: "${APP_DATASOURCE_PASSWORD:-ca_skeleton}"
TZ: "UTC"
volumes:
- type: volume
source: caskeleton-db-data
target: /var/lib/postgresql/data
ports:
- "127.0.0.1:5433:5432"
networks:
- caskeleton-infra
healthcheck:
test:
[
"CMD-SHELL",
"pg_isready -U ${APP_DATASOURCE_USERNAME:-ca_skeleton} -d ${POSTGRES_DB:-ca_skeleton}",
]
interval: 10s
timeout: 5s
retries: 5
start_period: 30s
# ---- MongoDB -----------------------------------------------------------------
# A replica set of one. Single-node is still a replica set: transactions and change streams need
# one, and a standalone mongod that "works for reads" is a deployment that discovers the
# difference at the first transaction.
mongo:
profiles:
- local-mongo
- all-adapters
image: mongo:8.0.16
command: ["mongod", "--replSet", "rs0", "--bind_ip_all"]
volumes:
- type: volume
source: caskeleton-mongo-data
target: /data/db
networks:
- caskeleton-infra
healthcheck:
test: ["CMD", "mongosh", "--quiet", "--eval", "db.adminCommand('ping').ok"]
interval: 10s
timeout: 5s
retries: 10
start_period: 20s
mongo-rs-init:
profiles:
- local-mongo
- all-adapters
image: mongo:8.0.16
depends_on:
mongo:
condition: service_healthy
# Idempotent: rs.initiate() on an already-initiated set returns an error this swallows, so the
# lane can be re-run against a surviving volume without a manual reset.
command:
- mongosh
- --host
- mongo
- --quiet
- --eval
- >-
try { rs.initiate({_id:'rs0',members:[{_id:0,host:'mongo:27017'}]}) }
catch (e) { if (!/already initialized/i.test(e.message)) { throw e } }
networks:
- caskeleton-infra
restart: "no"
# ---- Kafka -------------------------------------------------------------------
kafka:
profiles:
- local-messaging
- local-messaging-outbox
- all-adapters
image: apache/kafka:3.8.0
environment:
KAFKA_NODE_ID: "1"
KAFKA_PROCESS_ROLES: "broker,controller"
KAFKA_LISTENERS: "PLAINTEXT://:9092,CONTROLLER://:9093"
KAFKA_ADVERTISED_LISTENERS: "PLAINTEXT://kafka:9092"
KAFKA_CONTROLLER_QUORUM_VOTERS: "1@kafka:9093"
KAFKA_CONTROLLER_LISTENER_NAMES: "CONTROLLER"
KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: "CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT"
KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: "1"
KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: "1"
KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: "1"
networks:
- caskeleton-infra
healthcheck:
test:
["CMD-SHELL", "/opt/kafka/bin/kafka-broker-api-versions.sh --bootstrap-server kafka:9092"]
interval: 10s
timeout: 10s
retries: 12
start_period: 30s
# ---- Redis — local compose contract for the shipped Redis runtime ----------------
# Authenticated the way a deployment authenticates, with the lanes' test-fixture accounts:
# infra/redis-sdk/acl/lane-fixture-accounts.acl, the same file the Redis topology lanes use, mounted
# as it is rather than copied. It is not a deployment file — its passwords are public and it carries
# a lane-only `+@all` account (infra/redis-sdk/acl/README.md). Its first line turns the passwordless
# `default` user off, so the application connects as the named accounts the lane contract gives it
# (compose-profile-contracts.json, $redisComment).
#
# This Redis was open and the lanes declared app.redis.authentication.anonymous-access-accepted.
# The application then logged that trade, and the missing advanced account, as two startup
# warnings — correctly, because in production both are risks — and every Redis lane failed its
# "startup is silent" check. Quieting the warning would hide the same trade in production; the
# lane now authenticates the way a deployment does instead.
#
# The passwords are the file's fixture values (infra/redis-sdk/acl/README.md); this container is
# on the lane's internal network only and publishes no port.
redis:
profiles:
- local-redis
- all-adapters
image: redis:7.4
command:
- redis-server
- --appendonly
- "no"
- --save
- ""
- --aclfile
- /etc/redis/acl/lane-fixture-accounts.acl
volumes:
- type: bind
source: ./infra/redis-sdk/acl
target: /etc/redis/acl
read_only: true
networks:
- caskeleton-infra
healthcheck:
# As the application account: with `default` off, an unauthenticated PING answers NOAUTH.
test:
- "CMD-SHELL"
- "[ \"$$(redis-cli --user ca-skeleton-application --pass fixture-application --no-auth-warning ping)\" = PONG ]"
interval: 5s
timeout: 3s
retries: 12
start_period: 5s
# ---- Mailpit — the reference SMTP provider for notification serving ----------
mailpit:
profiles:
- local-notification-serving
- local-notification-handoff
- all-adapters
image: axllent/mailpit:v1.21
environment:
MP_SMTP_AUTH_ACCEPT_ANY: "1"
# MP_SMTP_AUTH_ALLOW_INSECURE is deliberately absent, and Mailpit refuses to start with both:
# "TLS cannot be required with --smtp-auth-allow-insecure". It existed to permit credentials
# over a plaintext connection, which is exactly what requiring STARTTLS removes the need for —
# any AUTH now happens inside the TLS session.
# STARTTLS, required. Not a hardening extra: SmtpProviderProperties.TlsMode has two members and
# neither is plaintext, so the platform cannot describe an unencrypted relay at all. A lane that
# wanted a plaintext Mailpit would be asking for a transport the type refuses to express, and
# the honest way to satisfy it is to give the relay a certificate.
MP_SMTP_TLS_CERT: /run/mailpit-tls/server.crt
MP_SMTP_TLS_KEY: /run/mailpit-tls/server.key
MP_SMTP_REQUIRE_STARTTLS: "true"
volumes:
# Generated per run by the qualification wrapper for the host name `mailpit`, and removed on
# teardown, exactly like the PostgreSQL lane certificate. A committed test certificate is a
# private key in Git.
- type: bind
source: ./infra/mailpit/tls
target: /run/mailpit-tls
read_only: true
networks:
- caskeleton-infra
healthcheck:
test: ["CMD", "/mailpit", "readyz"]
interval: 5s
timeout: 3s
retries: 12
start_period: 5s
# ---- MinIO -------------------------------------------------------------------
minio:
profiles:
- shared-infra
- prod-smoke
image: *local-minio-image
command: ["server", "/data"]
environment:
MINIO_ROOT_USER: "${MINIO_ROOT_USER:-caskeleton}"
MINIO_ROOT_PASSWORD: "${MINIO_ROOT_PASSWORD:-caskeleton-local}"
volumes:
- type: volume
source: caskeleton-minio-data
target: /data
networks:
- caskeleton-infra
healthcheck:
test: ["CMD", "mc", "ready", "local"]
interval: 10s
timeout: 5s
retries: 10
start_period: 10s
# Bucket and policy bootstrap. Not a substitute for the round trip: creating a bucket proves the
# server accepts an admin command, not that an object survives being written and read back.
minio-init:
profiles:
- shared-infra
- prod-smoke
# The client from the same supplier as the server. cgr.dev/chainguard/minio-client was not used:
# it has no shell, and the bootstrap below is a shell script.
image: "${LOCAL_MINIO_MC_IMAGE:-pgsty/mc@sha256:ce62c9053c69ce12a527a322345b5ad9f44b5f8a7b8189f82e516f2e3f30f1d8}"
depends_on:
minio:
condition: service_healthy
entrypoint: ["/bin/sh", "/opt/minio/bucket-bootstrap.sh"]
environment:
MINIO_ENDPOINT: "http://minio:9000"
MINIO_ROOT_USER: "${MINIO_ROOT_USER:-caskeleton}"
MINIO_ROOT_PASSWORD: "${MINIO_ROOT_PASSWORD:-caskeleton-local}"
MINIO_BUCKET: "${MINIO_BUCKET:-ca-skeleton-objects}"
volumes:
- type: bind
source: ./infra/minio/init
target: /opt/minio
read_only: true
networks:
- caskeleton-infra
restart: "no"
# ---- Keycloak ----------------------------------------------------------------
keycloak:
profiles:
- local-graphql
- local-notification-ingest
- local-notification-serving
- local-notification-handoff
- shared-infra
- prod-smoke
- all-adapters
image: quay.io/keycloak/keycloak:26.0
# The wrapper reads the client secret from a mounted file and execs kc.sh. The realm artifact
# carries only a ${...} reference, so no secret value is in Git, in the rendered config, or on a
# command line.
entrypoint: ["/bin/bash", "/opt/keycloak-entrypoint/entrypoint.sh"]
environment:
KC_BOOTSTRAP_ADMIN_USERNAME: "${KEYCLOAK_ADMIN:-admin}"
KC_BOOTSTRAP_ADMIN_PASSWORD: "${KEYCLOAK_ADMIN_PASSWORD:-admin}"
KC_HEALTH_ENABLED: "true"
volumes:
- type: bind
source: ./infra/keycloak/entrypoint.sh
target: /opt/keycloak-entrypoint/entrypoint.sh
read_only: true
- type: bind
source: ./infra/keycloak/realms
target: /opt/keycloak/data/import
read_only: true
secrets:
- keycloak-graphql-smoke-client-secret
networks:
- caskeleton-infra
healthcheck:
test:
- "CMD-SHELL"
- "exec 3<>/dev/tcp/127.0.0.1/9000 && echo -e 'GET /health/ready HTTP/1.1\\r\\nHost: localhost\\r\\nConnection: close\\r\\n\\r\\n' >&3 && cat <&3 | grep -q '\"status\": \"UP\"'"
interval: 10s
timeout: 5s
retries: 20
start_period: 30s
# ---- Capability schema streams ------------------------------------------------
# Two pre-start one-shots, in this order, because a capability stream is an operator sequence
# rather than a property.
#
# Install: each stream under db/migration/jpa keeps its own Flyway history table — they all declare
# a V1, so one Flyway pointed at all of them fails outright — and each registers itself
# INSTALLED_INACTIVE.
#
# Promote: an operator sanctions the installed schema, and the application refuses to start until
# that has happened. That is the fail-closed half of the same design, so it cannot be folded into
# the install step without making "the tables exist" and "this is sanctioned" the same event.
#
# They are also two images because they must be: flyway/flyway ships no psql, so the promotion
# could not have run in the migration container at all.
#
# Both run before `up`, not with the smoke clients after it — the application is what they are a
# precondition for. The lane contract's preStartServices carries that ordering.
db-migrate-capabilities:
profiles:
- local-notification-ingest
- local-notification-serving
- local-notification-handoff
- local-fileserver
- all-adapters
image: flyway/flyway:11.1.0
depends_on:
db:
condition: service_healthy
entrypoint: ["/bin/sh", "/opt/capability-streams/apply-capability-streams.sh"]
environment:
PGHOST: "db"
PGUSER: "${APP_DATASOURCE_USERNAME:-ca_skeleton}"
PGPASSWORD: "${APP_DATASOURCE_PASSWORD:-ca_skeleton}"
PGDATABASE: "${POSTGRES_DB:-ca_skeleton}"
CAPABILITY_STREAMS: "${CAPABILITY_STREAMS:-}"
volumes:
- type: bind
source: ./infra/postgres/apply-capability-streams.sh
target: /opt/capability-streams/apply-capability-streams.sh
read_only: true
# The whole migration tree, not just db/migration/jpa: the application's own postgresql stream
# has to be installed first, or the capability tables arrive in a schema whose flyway_schema_history
# does not exist yet and the application refuses to start — which is its baseline-on-migrate: false
# policy working as designed.
- type: bind
source: ./src/adapter/outbound/persistence-jpa/src/main/resources/db/migration
target: /flyway/sql
read_only: true
# Each capability stream from the leaf that owns it, beside rather than inside /flyway/sql: a
# bind mount nested in that read-only one would need its mount point created in the source
# tree. They moved out of persistence-jpa with their capabilities, and the mount above stopped
# reaching them — the script then refused with "no such stream".
- type: bind
source: ./src/adapter/outbound/persistence-notification/src/main/resources/db/migration/jpa/notification-platform
target: /flyway/streams/notification-platform
read_only: true
- type: bind
source: ./src/adapter/outbound/persistence-fileserver/src/main/resources/db/migration/jpa/fileserver
target: /flyway/streams/fileserver
read_only: true
networks:
- caskeleton-infra
restart: "no"
db-promote-capabilities:
profiles:
- local-notification-ingest
- local-notification-serving
- local-notification-handoff
- local-fileserver
- all-adapters
image: postgres:16-alpine
depends_on:
db:
condition: service_healthy
entrypoint: ["/bin/sh", "/opt/capability-streams/promote-capability-streams.sh"]
environment:
PGHOST: "db"
PGUSER: "${APP_DATASOURCE_USERNAME:-ca_skeleton}"
PGPASSWORD: "${APP_DATASOURCE_PASSWORD:-ca_skeleton}"
PGDATABASE: "${POSTGRES_DB:-ca_skeleton}"
CAPABILITY_STREAMS: "${CAPABILITY_STREAMS:-}"
volumes:
- type: bind
source: ./infra/postgres/promote-capability-streams.sh
target: /opt/capability-streams/promote-capability-streams.sh
read_only: true
networks:
- caskeleton-infra
restart: "no"
# The GraphQL transport, as a request. auth-smoke proves a token can be obtained and that public
# health answers; this proves /graphql is guarded and that an authenticated query executes.
graphql-smoke:
profiles:
- local-graphql
- all-adapters
image: curlimages/curl:8.10.1
depends_on:
keycloak:
condition: service_healthy
# uid 0 for the mounted 0600 client secret, same as auth-smoke.
user: "0:0"
entrypoint: ["/bin/sh", "/opt/graphql-smoke/graphql-smoke.sh"]
environment:
APP_BASE_URL: "http://app:8080"
KEYCLOAK_ISSUER: "http://keycloak:8080/realms/ca-skeleton"
KEYCLOAK_CLIENT_ID: "ca-skeleton-api"
# Spring for GraphQL serves its own endpoint through a router function rather than an
# annotated controller, so the presentation base-path prefix does not apply to it.
GRAPHQL_PATH: "${GRAPHQL_PATH:-/graphql}"
volumes:
- type: bind
source: ./infra/graphql/smoke
target: /opt/graphql-smoke
read_only: true
secrets:
- keycloak-graphql-smoke-client-secret
networks:
- caskeleton-infra
restart: "no"
# ---- One-shot smoke clients --------------------------------------------------
# Never `up --wait` targets. Each is run with `run --rm` and must exit zero; a missing, skipped or
# non-zero one fails its lane rather than being treated as "not applicable".
auth-smoke:
profiles:
- local-graphql
- shared-infra
- prod-smoke
- all-adapters
image: curlimages/curl:8.10.1
depends_on:
keycloak:
condition: service_healthy
# The client secret is written on the host at mode 0600 by the qualification wrapper and mounted
# in. The Keycloak image happens to run as the same uid the wrapper writes as; this image runs as
# uid 100, so it read "Permission denied" and the lane failed on the smoke client rather than on
# anything it was checking. Compose ignores the secret's uid/gid/mode options outside swarm, so
# the container reads it as root instead. The two alternatives are both worse: loosening the host
# file to world-readable leaves a credential readable by every process on the machine, and passing
# the value as an environment variable puts it in `docker compose config` output and in ps.
user: "0:0"
entrypoint: ["/bin/sh", "/opt/auth-smoke/auth-smoke.sh"]
environment:
# The same issuer URL the application is given. A token obtained from one URL and validated
# against another proves nothing, and localhost means a different host inside each container.
KEYCLOAK_ISSUER: "http://keycloak:8080/realms/ca-skeleton"
KEYCLOAK_CLIENT_ID: "ca-skeleton-api"
APP_BASE_URL: "http://app:8080"
# Supplied per runtime, because the same endpoint has two addresses: application-local.yml
# pins presentation.api-base-path to /api and the shipped default is /v1. The qualification
# wrapper exports the value that matches the lane's Spring runtime.
APP_HEALTH_PATH: "${APP_HEALTH_PATH:-/v1/healthcheck}"
volumes:
- type: bind
source: ./infra/keycloak/smoke
target: /opt/auth-smoke
read_only: true
secrets:
- keycloak-graphql-smoke-client-secret
networks:
- caskeleton-infra
restart: "no"
# The server image, not the mc client image: the mc image ships no sed, grep or cmp, and the round-trip
# client needs a digest tool. See infra/minio/smoke/object-storage-smoke.sh for how that went
# unnoticed. The lane already pulls this image for the server itself.
object-storage-smoke:
profiles:
- shared-infra
- prod-smoke
image: *local-minio-image
depends_on:
minio-init:
condition: service_completed_successfully
entrypoint: ["/bin/sh", "/opt/minio-smoke/object-storage-smoke.sh"]
environment:
MINIO_ENDPOINT: "http://minio:9000"
MINIO_ROOT_USER: "${MINIO_ROOT_USER:-caskeleton}"
MINIO_ROOT_PASSWORD: "${MINIO_ROOT_PASSWORD:-caskeleton-local}"
MINIO_BUCKET: "${MINIO_BUCKET:-ca-skeleton-objects}"
volumes:
- type: bind
source: ./infra/minio/smoke
target: /opt/minio-smoke
read_only: true
networks:
- caskeleton-infra
restart: "no"
notification-smoke:
profiles:
- local-notification-ingest
- local-notification-serving
- local-notification-handoff
- all-adapters
image: curlimages/curl:8.10.1
depends_on:
keycloak:
condition: service_healthy
# uid 0 for the same reason auth-smoke uses it: the mounted client secret is mode 0600 on the
# host and this image otherwise runs as uid 100, which reads "Permission denied". The lane then
# fails on the smoke client rather than on anything it was checking.
user: "0:0"
entrypoint: ["/bin/sh", "/opt/notification-smoke/notification-smoke.sh"]
environment:
APP_BASE_URL: "http://app:8080"
MAILPIT_BASE_URL: "http://mailpit:8025"
# ingest | serving | handoff-verify — which phase of the lane this invocation is.
#
# No default, deliberately. It defaulted to `ingest`, and local-notification-serving therefore
# ran the ingest assertions — "accepted, and nothing was delivered" — against an application in
# SERVING mode. The lane passed while testing the opposite of what it is named for, and would
# have kept passing for as long as the check happened to run before the dispatch worker. An
# unset value now renders empty and the client refuses it.
# `:-` and not a value: an explicit empty default keeps Compose from warning about an unset
# variable on every lane that never runs this client, while still rendering empty so the
# client refuses it.
NOTIFICATION_SMOKE_PHASE: "${NOTIFICATION_SMOKE_PHASE:-}"
# Submission and template publication are authenticated like every other non-public path, so
# this client obtains a token the same way auth-smoke does — client credentials against the
# same issuer URL the application validates against.
APP_BASE_PATH: "${APP_BASE_PATH:-/api}"
KEYCLOAK_ISSUER: "http://keycloak:8080/realms/ca-skeleton"
KEYCLOAK_CLIENT_ID: "ca-skeleton-api"
volumes:
- type: bind
source: ./infra/notification/smoke
target: /opt/notification-smoke
read_only: true
# The handoff lane runs this client twice in one project and the second run needs the request
# id the first accepted, so the state lives in a named volume that outlives a `run --rm`
# container and is removed with the project by the teardown's --volumes.
#
# Its own path, not a subdirectory of the script mount above: a volume nested inside a
# read-only bind cannot be created, because the runtime has to mkdir the mountpoint in a
# filesystem it was just told is read-only.
- type: volume
source: caskeleton-notification-smoke-state
target: /opt/notification-smoke-state
secrets:
- keycloak-graphql-smoke-client-secret
networks:
- caskeleton-infra
restart: "no"
networks:
caskeleton-infra:
driver: bridge
volumes:
caskeleton-notification-smoke-state:
driver: local
caskeleton-db-data:
driver: local
caskeleton-mongo-data:
driver: local
caskeleton-minio-data:
driver: local
secrets:
# Written per run at mode 0600 by the qualification wrapper and removed on teardown. The realm
# artifact references it by name; the value never reaches Git, a rendered config, a command line,
# or an evidence file.
keycloak-graphql-smoke-client-secret:
file: ./infra/keycloak/secrets/graphql-smoke-client-secret
-64
View File
@@ -1,64 +0,0 @@
# =============================================================================
# feature-container-runtime-contract — local infrastructure override
#
# Merge with base (and optionally dev):
# docker compose -f docker-compose.yml -f docker-compose.local.yml up
#
# Local intent:
# - Wires the app environment to point at the shared `db` service, which lives in
# docker-compose.infra.yml and starts only for lanes whose Compose profile names it.
# - Declares no depends_on: a depends_on aimed at a profiled service makes every lane that does
# not enable that profile fail to render at all, and ordering is the runtime-smoke wrapper's
# job — it knows which services a lane actually starts.
# - Keeps read-only filesystem and memory limits from the base compose.
# - Publishes the DB on the loopback interface only, so a host-side run
# (`./gradlew :app-bootstrap:bootRun`, IDE) reaches the same database the
# containerised app reaches over the internal `caskeleton-local` network.
# =============================================================================
services:
app:
# Optional, because src/.env is operator input and a fresh clone does not have one. Before this
# was marked optional, untracking that file made `docker compose config` fail outright on a
# clone — the environment override that exists for convenience became a hard prerequisite for
# rendering the stack at all. The tracked contract is src/.env.example; copy it.
env_file:
- path: ./src/.env
required: false
# Wire the app to the local Postgres service on the internal network.
environment:
# Explicit, not inherited. A Compose profile selects services; it says nothing about which
# environment the application believes it is in, and the two drifting is how a dev stack ends
# up running local's settings.
SPRING_PROFILES_ACTIVE: "local"
TZ: "UTC"
LANG: "C.UTF-8"
LC_ALL: "C.UTF-8"
# fallback matches env-keys.yaml SSOT default (30s); base compose grace is 60s.
APP_SERVER_SHUTDOWN_TIMEOUT: "${APP_SERVER_SHUTDOWN_TIMEOUT:-30s}"
APP_SERVER_SHUTDOWN: "graceful"
# Database connection — points to the local `db` service below.
# Override with your actual DB credentials in a local .env file.
APP_DATASOURCE_URL: "jdbc:postgresql://db:5432/${POSTGRES_DB:-ca_skeleton}"
APP_DATASOURCE_USERNAME: "${APP_DATASOURCE_USERNAME:-ca_skeleton}"
APP_DATASOURCE_PASSWORD: "${APP_DATASOURCE_PASSWORD:-ca_skeleton}"
healthcheck:
test:
- "CMD"
- "wget"
- "--no-verbose"
- "--tries=1"
- "--spider"
- "http://localhost:8080/api/healthcheck"
interval: 5s
timeout: 3s
start_period: 20s
retries: 12
networks:
- caskeleton-infra
networks:
# Defined in docker-compose.infra.yml, where the services that share it live.
caskeleton-infra:
external: false
-107
View File
@@ -1,107 +0,0 @@
# =============================================================================
# feature-container-runtime-contract — base docker-compose service definition
#
# Usage:
# docker compose up # base only
# docker compose -f docker-compose.yml -f docker-compose.dev.yml up # dev override
# docker compose -f docker-compose.yml -f docker-compose.local.yml up # local override
#
# Graceful-shutdown sync table (feature-container-runtime-contract D5):
# App shutdown timeout : 30s (APP_SERVER_SHUTDOWN_TIMEOUT — SSOT: docs/registries/
# env-keys.yaml, owner feature-env-driven-runtime-configuration)
# Async executor wait : 19s (AsyncExecutorConfig.AWAIT_TERMINATION_SECONDS)
# Container preStop : 5s (handled by the orchestrator / stop_grace_period offset)
# stop_grace_period : 60s (30s app drain + 19s async + 5s preStop + 6s safety margin)
#
# The drain and the async wait are consecutive, not concurrent: Spring finishes the lifecycle
# phase (the web server's graceful drain) before it destroys the executor, which then waits for
# its queue. A 40s grace let the container be killed 9s into that wait (07-07).
# DeveloperExperienceContractTest fails when this value is below the sum.
#
# Ownership: env-driven-config owns the app shutdown *value* (30s); this contract owns the
# *relationship* (stop_grace_period >= app timeout + async wait + preStop + margin). The grace is therefore
# sized UP to the env-keys SSOT value (30s) — you do not shrink the app drain window to fit an
# arbitrary grace. This resolves the earlier 20s/35s drift, which had assumed an app-timeout
# value this branch does not own (env-keys.yaml is the SSOT and sets 30s).
#
# Memory limit (D4):
# The container memory limit MUST be set for -XX:MaxRAMPercentage=75 to be meaningful.
# Default 512m suits a small service; adjust per deployment.
# =============================================================================
services:
app:
build:
context: src/
dockerfile: Dockerfile
args:
RELEASE_VERSION: "${RELEASE_VERSION:-0.0.1}"
BUILD_VERSION: "${BUILD_VERSION:-0.0.1+0000000}"
GIT_SHA: "${GIT_SHA:-0000000}"
SOURCE_URL: "${SOURCE_URL:-https://example.invalid/ca-tmpl}"
# default = the composition a service ships. scripts/run-compose-runtime-smoke.sh sets
# qualification: every capability module present, each lane switching on what it tests.
COMPOSITION: "${COMPOSITION:-default}"
# The composition is in the tag, so a lane's qualification image is never reused as the
# default one (Compose reuses a matching tag instead of building).
image: caskeleton:${BUILD_VERSION:-0.0.1_local_0000000}-${COMPOSITION:-default}
# Generated per run by scripts/run-compose-runtime-smoke.sh and removed on teardown. Seven values
# have no inline default on purpose — the datasource address and credential, the application
# name, and the JWT issuer and audience — so a lane has to supply them, and a lane that borrowed
# the developer's own src/.env would be reproducible only on that developer's machine. Optional,
# so an ordinary `docker compose up` is unaffected.
env_file:
- path: ./src/.env.lane
required: false
ports:
- "${APP_SERVER_PORT:-8080}:8080"
# Management (health, info, prometheus — answered without authentication) on loopback only:
# published on every interface it reaches the whole LAN (07-13). The smoke lanes read it from
# inside the container, so they need no host port at all.
- "127.0.0.1:9001:9001"
environment:
TZ: "UTC"
LANG: "C.UTF-8"
LC_ALL: "C.UTF-8"
# Graceful shutdown — fallback matches the env-keys.yaml SSOT default (30s).
# Override via .env or docker compose --env-file if you need a different value.
APP_SERVER_SHUTDOWN_TIMEOUT: "${APP_SERVER_SHUTDOWN_TIMEOUT:-30s}"
APP_SERVER_SHUTDOWN: "graceful"
# ---- Read-only root filesystem (D2) -------------------------------------
# The application must write only to the tmpfs mounts declared below.
# /tmp — Tomcat basedir (see -Dserver.tomcat.basedir=/tmp in Dockerfile).
# /var/tmp/heap — heap dump landing zone (see -XX:HeapDumpPath=/var/tmp/heap).
read_only: true
tmpfs:
- /tmp:mode=1777,size=128m
- /var/tmp/heap:mode=1777,size=512m
# No volume: the shipped composition keeps nothing on disk. A capability that does brings its
# mount in its own overlay file under infra/<capability>/compose/, added with -f when the
# capability is selected, so this file never names one (07-08).
# ---- Memory limit (D4) --------------------------------------------------
# Must be set so -XX:MaxRAMPercentage=75 can compute a meaningful heap bound.
mem_limit: 512m
memswap_limit: 512m
# ---- Graceful shutdown (D5) ---------------------------------------------
# stop_grace_period = app drain (30s, env-keys SSOT) + async wait (19s) + preStop (5s)
# + margin (6s) = 60s.
stop_grace_period: 60s
# ---- Health check -------------------------------------------------------
# Targets the actuator readiness probe on the management port (9001).
# The warning that used to stand here — that this probe would report UNHEALTHY until two
# parallel branches merged — outlived the branches. src/Dockerfile removed its copy and said
# why: "a stale warning about a healthcheck is the kind of comment that gets a real red
# container ignored."
healthcheck:
test:
- "CMD"
- "wget"
- "--no-verbose"
- "--tries=1"
- "--spider"
- "http://localhost:9001/actuator/health/readiness"
interval: 30s
timeout: 5s
start_period: 60s
retries: 3
restart: unless-stopped
+2 -2
View File
@@ -27,11 +27,11 @@ lanes and CI; it is not a deployment artifact.
| Capability | Enabled key (property / env, default) | IMPLEMENTED | WIRED | QUALIFIED | Evidence |
| --- | --- | --- | --- | --- | --- |
| Relational persistence (JPA/PostgreSQL) | `ca-skeleton.persistence-jpa.enabled` / `APP_PERSISTENCE_JPA_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:persistence-jpa')`) | yes | Not in the default composition. The one line brings everything — its own `AutoConfiguration.imports` (`PersistenceJpaAutoConfiguration`, `PersistenceJpaRuntimeConfig`, `JpaStartupAutoConfiguration`), its environment handling (`JpaActivationEnvironmentPostProcessor`, `spring.factories`: readiness `db` while on; with `false` it also excludes Boot's JDBC, Hibernate, Spring Data JPA and Flyway auto-configuration, so no DataSource is bound), the startup guards (Flyway strategy, datasource/OSIV/DDL/pool/TLS/vendor checks, exit codes unchanged) and its settings (`config/module-defaults/persistence-jpa.yml`). `persistence-jpa:PersistenceJpaCapabilityAssemblyTest` proves the module assembles on its own; the `postgresql*IntegrationTest` readiness lanes, run by `integration-main.yml` → `integration-check` (`:integrationCheck`), qualify it against PostgreSQL. `sample-portfolio` selects it by its build dependency and the module's auto-configuration (no broad scan of the persistence package). `bootRunH2` adds the module to its own classpath only. |
| Relational persistence (JPA/PostgreSQL) | `ca-skeleton.persistence-jpa.enabled` / `APP_PERSISTENCE_JPA_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:persistence-jpa')`) | yes | Not in the default composition. The one line brings everything — its own `AutoConfiguration.imports` (`PersistenceJpaAutoConfiguration`, `PersistenceJpaRuntimeConfig`, `JpaStartupAutoConfiguration`), its environment handling (`JpaActivationEnvironmentPostProcessor`, `spring.factories`: readiness `db` while on; with `false` it also excludes Boot's JDBC, Hibernate, Spring Data JPA and Flyway auto-configuration, so no DataSource is bound), the startup guards (Flyway strategy, datasource/OSIV/DDL/pool/TLS/vendor checks, exit codes unchanged) and its settings (`config/module-defaults/persistence-jpa.yml`). `persistence-jpa:PersistenceJpaCapabilityAssemblyTest` proves the module assembles on its own; the `postgresql*IntegrationTest` readiness lanes, run by `integration-main.yml` → `integration-check` (`:integrationCheck`), qualify it against PostgreSQL. `bootRunH2` adds the module to its own classpath only. |
| Document persistence (MongoDB) | `ca-skeleton.persistence-mongo.enabled` / `APP_PERSISTENCE_MONGO_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:persistence-mongo')`) | yes | On when present; `false` also excludes Boot's Mongo auto-configuration (`MongoCapabilityActivationTest`). The connection-source rule (`SPRING_MONGODB_URI` or the selected profile's `uri-secret`) is checked by the module's own `MongoDefaultsEnvironmentPostProcessor`. Six container lanes (`mongoReplicaSetTest`, `mongoFailoverTest`, …), run by `integration-main.yml` → `integration-check` (`:integrationCheck`) |
| Messaging (Kafka) | `app.messaging.enabled` / `APP_MESSAGING_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:messaging-kafka')`, which brings the application bridge, the legacy `KafkaSender` seam and the vendored platform with its Kafka transport) | Kafka only | On when present (`KafkaCapabilityActivationTest`). `messaging-kafka:messagingCertificationTest` behind `verifyMessagingCertificationEvidence`, run by `messaging-certification.yml`; the starter's `integrationTest` is the live Kafka round trip. Kafka is the only registered broker; the RabbitMQ broker keys were removed (no transport). |
| Redis capabilities (cache / rate-limit / lease / idempotency) | `app.redis.enabled` / `APP_REDIS_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:cache-redis')`, which brings `redis-runtime`) | yes | `cache-redis:redisContainerContractTest` (Testcontainers Redis, `integrationCheck`); `cache-redis:redisTopologyTest`, run by `redis-sdk-topology.yml`. Not in the default composition. On when present; `false` contributes no Redis bean — no settings, client, connection, thread or health contributor. The module owns its readiness contribution (`RedisReadinessGroupPostProcessor`, `spring.factories`) and its settings (`config/module-defaults/cache-redis.yml`: `app.redis.enabled`, `app.rate-limit.*`, the Redis `ca-skeleton.capabilities.*`). No `app-bootstrap` main source names a Redis type. |
| Request idempotency | `APP_IDEMPOTENCY_PROVIDER` (`disabled` \| `redis` \| `postgresql`; a selector, not an on/off key) | yes | yes | Redis and PostgreSQL | One generation: the application `IdempotencyExecutor`, built once by `composition:idempotency` (`IdempotencyAutoConfiguration`) over the one store the selected provider contributes (`cache-redis` or `persistence-jpa`); startup is refused unless exactly one store exists. `app-bootstrap` and `sample-portfolio` both take that module with one `runtimeOnly` line, so there is no second assembly. Redis is covered by the row above. PostgreSQL has `persistence-jpa:postgresqlIdempotencyIntegrationTest`, run by `integration-main.yml` → `integration-check` (`:integrationCheck`). The `postgresql` provider refuses a non-PostgreSQL data source, so `bootRunH2` uses `disabled` or `redis`. Each store comes with its module: `postgresql` needs the persistence-jpa line, `redis` the cache-redis one. |
| Request idempotency | `APP_IDEMPOTENCY_PROVIDER` (`disabled` \| `redis` \| `postgresql`; a selector, not an on/off key) | yes | yes | Redis and PostgreSQL | One generation: the application `IdempotencyExecutor`, built once by `composition:idempotency` (`IdempotencyAutoConfiguration`) over the one store the selected provider contributes (`cache-redis` or `persistence-jpa`); startup is refused unless exactly one store exists. `app-bootstrap`이 그 모듈을 `runtimeOnly` 한 줄로 받고, 다른 조립은 없다. Redis is covered by the row above. PostgreSQL has `persistence-jpa:postgresqlIdempotencyIntegrationTest`, run by `integration-main.yml` → `integration-check` (`:integrationCheck`). The `postgresql` provider refuses a non-PostgreSQL data source, so `bootRunH2` uses `disabled` or `redis`. Each store comes with its module: `postgresql` needs the persistence-jpa line, `redis` the cache-redis one. |
| Transactional outbox relay | `ca-skeleton.outbox.enabled` / `APP_OUTBOX_ENABLED`, `false` (+ `APP_OUTBOX_RELAY_ENABLED`, `false`; persistence-jpa settings) | yes | yes (with the persistence-jpa line; the scheduler also needs the messaging-kafka line) | yes | The store and its settings are persistence-jpa's; the relay (`OutboxConfig`) is application composition in `app-bootstrap` because a driven adapter must not build or call a use case. It turns on only when an `OutboxStorePort` bean exists, and the scheduler only when an `OutboxMessagePublishPort` does (the messaging bridge), each ordered after its contributor by `afterName` — so an environment with no publisher keeps its PENDING rows. The bridge registers no stand-in publisher: a present-and-enabled bridge with a blank broker and no canonical transport is refused at startup. `postgresqlLegacyOutboxConcurrentRelayIntegrationTest` qualifies claim/fencing against PostgreSQL. |
| Notification platform | `ca-skeleton.notification.platform.enabled` / `APP_NOTIFICATION_PLATFORM_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':composition:notification-platform')`, plus the persistence-jpa line) | claim-scoped | Not in the default composition. The one line brings the use-case assembly, `adapter:outbound:notification`, the HTTP surface `adapter:inbound:web-notification` and its own settings (`config/module-defaults/notification.yml`), each registered through the module's own `AutoConfiguration.imports`; `adapter:inbound:web` no longer depends on `application-notification`. `verifyNotificationEvidence` refuses a grade in `docs/notification/support-matrix.md` that no proven claim backs; run by `notification-platform.yml`. There is no real-SMTP lane, and the matrix says so rather than implying one. |
| File server platform | `app.fileserver-platform.enabled` / `APP_FILESERVER_PLATFORM_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':composition:fileserver-platform')`, plus the persistence-jpa line) | yes | On when present; module-owned `config/module-defaults/fileserver.yml` also carries the servlet multipart ceiling. `app-bootstrap:integrationTest` → `FileserverCompositionIntegrationTest` (required by the strict lane), run by `integration-main.yml` → `integration-check` (`:integrationCheck`) |
+4 -6
View File
@@ -60,12 +60,10 @@ GitHub Actions 워크플로는 `kubectl apply`, `helm upgrade`, `argocd app sync
| Argo CD Application 정의 | **없음.** GitOps 저장소에 둘 예정 |
| CI에서의 클러스터 접근 | 없음 — 유일했던 `kubectl apply`는 제거됨 |
`release.yml`의 fileserver certification 잡(`fileserver-pvc-certification` 등, 예전
`fileserver-certification.yml`)은 예외처럼 보이지만 아니다. PVC 매니페스트가 여전히 ReadWriteOnce를
선언하는지 **파일만** 확인하고, 클러스터에는 아무것도 적용하지 않는다. 실제 클러스터에서의 인증은
운영자가 `infra/fileserver/kubernetes/pvc-certification-job.yaml`을 직접 실행하고
`docs/fileserver/storage-certification.md`에 기록한다. 잡 이름이 "release"가 아니라 "certification"인
이유가 이것이다 — 이 잡은 릴리스하지 않는다.
PVC 매니페스트와 그 파일을 검사하던 `release.yml` 잡(`fileserver-pvc-certification`)은 2026-11-07에
지웠다(소유자 결정: Kubernetes·프록시 설정은 이 repo 밖). 클러스터 인증은 배포하는 쪽이
`docs/fileserver/storage-certification.md` 절차로 하고, volume 조건은 `docs/fileserver/operations.md`
「운영 환경이 지켜야 할 조건」에 있다.
## 규칙
+2 -5
View File
@@ -4,8 +4,8 @@
이 저장소에는 성격이 다른 두 종류의 검증이 섞여 있다.
1. **스켈레톤을 만드는 사람**에게 필요한 검증 — sample 모듈이 정말 제거 가능한가, optional 모듈
조합이 모두 빌드되는가, 레지스트리가 확장 가능한가.
1. **스켈레톤을 만드는 사람**에게 필요한 검증 — optional 모듈 조합이 모두 빌드되는가, 레지스트리가
확장 가능한가.
2. **스켈레톤을 가져다 서비스를 만드는 사람**에게 필요한 검증 — 내 애플리케이션의 테스트,
아키텍처 방향, 보안, 릴리스.
@@ -16,9 +16,6 @@
| 대상 | 무엇을 지키는가 |
| --- | --- |
| `:app-bootstrap:sampleOffTest`, `ci-quality-gates.yml`의 `sample-off` job | sample 픽스처를 지워도 애플리케이션이 빌드·부팅되는가 |
| `sample-portfolio` leaf 전체 | 참조 구현 |
| `Dockerfile.sample`, `docker-compose.*` 중 sample 관련 | 위와 동일 |
| `docs/superpowers/**` | 이 템플릿을 만든 과정의 설계/계획 기록 |
| `gradle/qualification/**` | 이 템플릿이 벤더링한 플랫폼(JPA, messaging)의 인증 체계 |
| `*-certification.yml`, `*-qualification.yml`, `jpa-next-*.yml` | 템플릿이 광고하는 지원 매트릭스의 근거 |
+2 -3
View File
@@ -113,9 +113,8 @@ The metadata store, session store, quota service, queues, ledger, and staging lo
`@ConditionalOnProperty(app.fileserver-platform.enabled)` even though the rest of
`adapter:outbound:persistence-jpa` is unconditional.
Without the gate, every composition root that includes the persistence module built these beans —
including `sample-portfolio`, which has no Fileserver — and each of them needs collaborators only
the Fileserver configuration provides. That is the same rule the design states for the transport
게이트가 없으면 persistence 모듈을 포함한 조립 루트는 Fileserver를 쓰지 않아도 이 bean들을 만들고, 그 bean마다
Fileserver 설정만 주는 협력 객체가 필요하다. That is the same rule the design states for the transport
surface, applied to persistence: no surface appears merely because the dependency is present.
`FileStateMachine` is bound alongside them, in `FileserverStorageConfiguration`. It had no
+33 -7
View File
@@ -83,13 +83,13 @@ The volume was remounted somewhere the probe can no longer prove a required capa
application refuses traffic rather than serving from storage it cannot publish to atomically.
```bash
kubectl apply -f infra/fileserver/kubernetes/pvc-certification-job.yaml
kubectl logs job/fileserver-pvc-certification
# staging과 content가 같은 파일 저장소(같은 장치 번호)인지 pod 안에서 본다
kubectl exec <pod> -- stat -c %d /var/lib/backend/files/staging /var/lib/backend/files/content
```
Compare the printed tuple with the certified one in `docs/fileserver/storage-certification.md`. A
mismatch in CSI driver, StorageClass, access mode, or mount options is the cause; the certification
does not carry across it.
`docs/fileserver/storage-certification.md`의 인증 절차로 지금 volume의 묶음(CSI driver, StorageClass,
접근 모드, backend, mount 옵션)을 다시 적고, 인증한 묶음과 비교한다. 하나라도 다르면 그것이 원인이다.
인증은 그 차이를 넘어 옮겨지지 않는다.
## Nginx delegation failure
@@ -97,9 +97,9 @@ does not carry across it.
The internal location is misconfigured, so the proxy cannot resolve the redirect it was handed.
프록시 설정의 내부 location(기본 `/__files/`)이 아래 「운영 환경이 지켜야 할 조건」을 지키는지 본다.
```bash
# The internal prefix must resolve to the content root and must be marked `internal`.
grep -A5 '__files' infra/fileserver/nginx/nginx.conf
curl -s $ADMIN/internal/fileserver/capabilities | jq '.capabilities.delegatedDownload'
```
@@ -110,6 +110,32 @@ slower but correct.
app.fileserver-platform.nginx.enabled=false
```
## 운영 환경이 지켜야 할 조건
이 repo는 프록시 설정 파일과 Kubernetes 매니페스트를 두지 않는다(2026-11-07 소유자 결정). 그 파일은 서비스를
배포하는 쪽의 인프라 repo가 갖는다. 그 파일이 지켜야 할 조건은 아래다.
**프런트 프록시(nginx `X-Accel-Redirect` 위임)** — `app.fileserver-platform.nginx.enabled=true`일 때
1. 내부 location(`app.fileserver-platform.nginx.internal-prefix`, 기본 `/__files/`)은 `internal`이다. 클라이언트가
그 경로를 직접 부르면 404이고 content 폴더에 닿지 않는다. 애플리케이션이 준 내부 redirect로만 닿는다.
2. 그 location의 `alias`는 저장 루트의 content 폴더다(기본 `/var/lib/backend/files/content/`). 애플리케이션은
절대 경로를 내보내지 않고 내부 접두사 아래 상대 URI만 내보낸다. 경로가 실제 위치가 되는 곳은 이 `alias`뿐이다.
3. 앱으로 넘기는 요청에서 클라이언트가 보낸 `X-Accel-Redirect` 헤더를 지운다. 남기면 호출자가 임의의 내부
객체를 가리킬 수 있다.
4. 업로드는 스트리밍으로 넘긴다(`proxy_request_buffering off`, 본문 크기 제한은 애플리케이션이 정하므로 프록시는
막지 않는다). 프록시가 큰 본문을 디스크에 버퍼링하면 쓰기가 두 번 일어난다.
5. 내부 location 응답에 `X-Content-Type-Options: nosniff`를 붙이고, 앱이 정한 `Content-Disposition`·
`Cache-Control`·`ETag`를 그대로 넘긴다. 올라온 내용이 자기 형식을 스스로 정하게 두지 않는다.
**Kubernetes 저장 volume**
1. PersistentVolumeClaim을 저장 루트(`/var/lib/backend/files`)에 마운트하고, 접근 모드는 `ReadWriteOnce`다.
`ReadWriteMany`(여러 노드의 동시 쓰기)는 인증하지 않았다(`support-matrix.md`).
2. pod `securityContext.fsGroup`을 이미지의 앱 그룹으로 둔다. 그래야 앱 계정이 volume에 쓸 수 있다.
3. 그 volume이 `storage-certification.md`의 인증 항목(같은 파일 저장소, 원자적 rename, `O_EXCL` 생성)을
통과해야 한다. 기동 때 `FileserverStartupValidator`도 같은 probe를 다시 돌린다.
## Cleanup backlog
**Signal** — `fileserver.cleanup{result="deferred"}` rising, or reclaimed bytes flat while deletes
+10 -8
View File
@@ -19,12 +19,15 @@ certification that does not name all five is not transferable.
## Running the certification
```bash
kubectl apply -f infra/fileserver/kubernetes/pvc-certification-job.yaml
kubectl logs job/fileserver-pvc-certification
```
이 repo는 인증 job 매니페스트를 두지 않는다(2026-11-07 소유자 결정). 배포하는 쪽이 대상 volume을 저장
루트(`/var/lib/backend/files`)에 마운트한 일회성 pod에서 아래를 차례로 확인한다.
The job writes a machine-readable result to the claim itself, carrying the full tuple:
1. `staging`과 `content` 폴더를 만들고, `staging`의 파일을 `content`로 `mv`해 원자적 rename이 되는지 본다.
2. 두 폴더의 장치 번호(`stat -c %d`)가 같은지 본다. 다르면 rename이 복사가 된다.
3. `set -o noclobber` 상태에서 같은 파일을 두 번 만들어 `O_EXCL` 생성이 막히는지 본다.
4. 결과와 함께 묶음(Kubernetes 버전, CSI driver, StorageClass, 접근 모드, backend, mount 옵션)을 기록한다.
결과는 묶음 전체를 담은 기계가 읽는 형식으로 그 volume에 남긴다:
```json
{
@@ -40,13 +43,12 @@ The job writes a machine-readable result to the claim itself, carrying the full
}
```
The job fails closed: a volume whose staging and content areas are on different stores is not
certified, because its publish would silently degrade to a copy.
2번이 실패하면 인증하지 않는다. staging과 content가 다른 저장소인 volume은 게시가 소리 없이 복사로 바뀐다.
## Network filesystems
```bash
docker compose -f infra/fileserver/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
```
+4 -5
View File
@@ -29,7 +29,6 @@ that does not exist, so a level can never outlive the test that justified it.
| NFSv4 ambiguity handling | Beta | `fileserver-nfs-ambiguity` |
| Large-file and slow-client performance | Beta | `fileserver-large-file-performance` |
| Multi-instance writer lease | Beta | `fileserver-multi-instance-lease` |
| Kubernetes ReadWriteOnce PVC | Limited | `fileserver-pvc-certification` (manifest checks in CI; cluster run is operator-driven) |
| Nginx `X-Accel-Redirect` delegation | Limited | `fileserver-http-contract` |
| Telemetry sensitive-data suppression | Stable | `fileserver-sensitive-telemetry-scan` |
| Documentation and support-claim coverage | Stable | `fileserver-documentation-gate` |
@@ -46,10 +45,10 @@ leaf puts `DispatcherServlet` on the classpath, so Boot resolves SERVLET.
These have no job, and therefore no claim:
- An automated Kubernetes cluster result. `fileserver-pvc-certification` validates the manifest on
every release and applies it only when a release cluster is configured; without one it warns and
records that nothing was certified. The cluster tuple is produced by an operator and read from
[storage-certification.md](storage-certification.md).
- Kubernetes PVC(ReadWriteOnce 포함). 이 repo는 클러스터 매니페스트와 그것을 검사하던 release job을
2026-11-07에 지웠다. volume이 지켜야 할 조건은 [operations.md](operations.md) 「운영 환경이 지켜야 할
조건」, 인증 절차는 [storage-certification.md](storage-certification.md)다. 클러스터 결과는 배포하는 쪽이
만든다.
- Kubernetes ReadWriteMany PVC. Concurrent writers across nodes are not certified.
- Windows NTFS as a production storage root. The filename policy strips the characters NTFS
+2 -2
View File
@@ -96,8 +96,8 @@ second `UPDATE`, and the entity graph is a cycle. Keep the association on one si
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`) runs it over the production graph and `SampleArchitectureTest` over the sample.
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:
+3 -4
View File
@@ -103,10 +103,9 @@ from its list that lock an existing table with no bound in force: `ALTER TABLE`,
FULL`; `REFERENCES` on the table it references, in a new table as much as in an `ALTER TABLE` (a
foreign key locks its parent against writes while it is added); `CREATE TRIGGER` and `DROP TRIGGER`
on their table; `UPDATE` and `DELETE`. It reads text, so a statement outside the list is not
checked. `MigrationLockWaitTest` runs it over every tree this leaf's database runs,
`SampleMigrationLockWaitTest` over the sample's stream; a service stream copies the latter with its
own directory. Both find the migrations the way Flyway does, decimal versions (`V22_1__`) included
(`VersionedMigrationFiles`, testkit). The migrations released before the rule wait unbounded and
checked. `MigrationLockWaitTest`는 이 leaf의 데이터베이스가 돌리는 모든 트리에 이 검사를 건다. 서비스
스트림은 이 테스트를 복사해 자기 폴더를 넣는다. 이 테스트는 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
+2 -2
View File
@@ -100,9 +100,9 @@ Docker-dependent lanes fail closed rather than skipping, matching the existing
| 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. |
| 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. |
| `settings.gradle.kts` module registration | Fail-closed 19-leaf registry | No registry change: leaf identity, Gradle path, allowed dependencies, and runtime memberships are unchanged. |
| `infra/jpa/{postgres,roles,toxiproxy}` | Repository already owns `infra/` | Created at the same repository-relative paths. |
| `infra/jpa/{postgres,roles,toxiproxy}` | Repository already owns `infra/` | 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. |
| release blocking aggregate | `jpaReleaseQualification` (persistence-jpa `build.gradle`) over `config/jpa/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. | |
| 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. | |
| 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. |
| 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. |
| 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". |
+3 -3
View File
@@ -91,6 +91,6 @@ drop an index another instance was about to finish building.
Startup refused because the runtime credential holds `CREATE`, or `search_path` contains an
unapproved schema.
This is not a false positive to be worked around. Re-provision from
`infra/jpa/roles/runtime-roles.sql`; the application's credential having DDL is the condition that
makes every other schema guarantee unenforceable.
This is not a false positive to be worked around. `docs/jpa/security.md` 「역할과 권한 — 운영 DB가
갖춰야 할 것」대로 권한을 다시 맞춘다. 애플리케이션 자격 증명이 DDL을 가지면 다른 schema 보장을 하나도
지킬 수 없다.
+35 -1
View File
@@ -14,7 +14,41 @@ The separation is what makes "Flyway owns schema change" enforceable rather than
the application's own credential cannot execute DDL, then no code path, no library, and no injected
statement can alter the schema at runtime, regardless of what the application intended.
`infra/jpa/roles/runtime-roles.sql` provisions them.
### 역할과 권한 — 운영 DB가 갖춰야 할 것
이 repo는 역할을 만드는 SQL 파일을 두지 않는다(2026-11-07 소유자 결정. 운영 DB 준비는 배포하는 쪽의
일이다). 운영 DB는 아래 조건을 지켜야 한다. 기동 때 `PostgreSqlRuntimeRoleVerifier`가 그중 런타임 역할의
`CREATE` 권한과 `search_path`를 다시 본다.
1. 애플리케이션 schema(예: `app`)는 migration 역할이 소유한다. 런타임 역할이 소유하지 않는다.
2. `PUBLIC`에서 데이터베이스 권한 전체와 `public` schema의 `CREATE`를 거둔다. PostgreSQL 15 전에는
`PUBLIC`이 `public` schema에 `CREATE`를 가져, 권한 없는 역할이 `search_path`로 진짜 객체를 가리는
객체를 만들 수 있었다.
3. 런타임 역할에는 `CONNECT`, 애플리케이션 schema의 `USAGE`, 그 schema 테이블의
`SELECT`·`INSERT`·`UPDATE`·`DELETE`, sequence의 `USAGE`·`SELECT`만 준다.
4. migration 역할이 앞으로 만들 테이블·sequence에도 같은 권한이 가도록 `ALTER DEFAULT PRIVILEGES`를
건다. 빠뜨리면 새 테이블을 더한 첫 배포가 런타임 권한 오류로 실패한다.
5. 런타임 역할에서 schema와 데이터베이스의 `CREATE`를 명시적으로 거둔다. 기동 검사가 보는 두 권한이다.
6. 관리 역할(COPY·backfill·정비용)은 런타임 역할과 같은 행 권한을 갖되 schema를 소유하지 않는다. 요청
경로는 이 역할을 쓰지 않는다.
7. 런타임·관리 역할의 `search_path`를 `app, pg_catalog`처럼 고정한다.
비밀번호는 배포 환경의 비밀 저장소에서 넣는다. repo에 두지 않는다.
### 서버 설정 — 플랫폼의 보장이 기대는 것
계약 테스트는 자기 컨테이너를 띄우므로(`PostgreSqlContainerFactory`) 이 설정이 필요 없다. 운영 DB에서
플랫폼의 보장이 성립하려면 아래 설정이 있어야 한다. 값은 출발점이다. 가장 느린 정상 쿼리를 재 보고 정한다.
| 설정 | 출발 값 | 왜 필요한가 |
| --- | --- | --- |
| `statement_timeout` | `30s` | 트랜잭션 안의 문장 하나가 요청보다 오래 사는 것을 막는 마지막 상한 |
| `idle_in_transaction_session_timeout` | `60s` | 열어 둔 채 쉬는 트랜잭션이 잠금과 snapshot을 붙잡아 쓰기와 vacuum을 막는 시간을 줄인다 |
| `lock_timeout` | `10s` | `PostgreSqlLockOptions`의 요청별 잠금 상한 아래에 까는 바닥 |
| `max_connections` | 배포 수에 맞춤 | 모든 인스턴스의 pool 합과, `REQUIRES_NEW`가 두 번째 연결을 잡는 경우를 함께 견딘다 |
| `default_transaction_isolation` | `read committed` | 바꾸면 격리 수준을 고르지 않은 모든 트랜잭션이 조용히 달라진다 |
확장(extension)은 필요 없다. JSONB, 배열, 범위, `SKIP LOCKED`, `ON CONFLICT`는 모두 PostgreSQL 본체 기능이다.
## Startup verification
+3 -3
View File
@@ -1,7 +1,7 @@
# JPA Persistence Platform — Support Matrix
**This document is a rendering. The machine-readable source is
[`src/config/jpa/release-registry.json`](../../src/config/jpa/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
mentioned became a supported version, whatever table or sentence produced the match. An Experimental
@@ -118,8 +118,8 @@ Each row is a way the platform could pass its tests and still be wrong in produc
### The audit mechanism
`audit/AuditableEntity` is the only one: `created_*`/`updated_*`, a 256-character actor, stamped
explicitly by the repository adapter. It is what the sample entities extend and what the migrations
were written for. A second, Spring Data listener-based mechanism (`auditing/AuditMetadata`) was never
explicitly by the repository adapter. 서비스의 엔티티는 이것을 상속하고, 마이그레이션도 이 열에
맞춰 썼다. A second, Spring Data listener-based mechanism (`auditing/AuditMetadata`) was never
composed and has been removed; `JpaAuditMechanismRule.entitiesUseExactlyOneAuditMechanism` keeps it
from coming back on an entity.
+1 -1
View File
@@ -35,7 +35,7 @@
- **기본값**: 서버가 만든다. domain `XIdFactory extends IdFactory<XId>` + `adapter:outbound:identifier`
구현. 문법은 id 값 객체 생성자에서 검사한다.
- **예외**: 클라이언트가 자연 키(주문번호 등)를 주는 기능은 그 키를 id로 쓴다. 이때 중복은 DB 유일성
제약이 막는다(04장). UUIDv7이 필요하면 `src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/adapter/outbound/identifier/UuidWorkLogIdFactory.java`처럼 바꾼다.
제약이 막는다(04장). UUIDv7이 필요하면 `src/adapter/outbound/identifier/src/main/java/dev/caskeleton/adapter/outbound/identifier/UuidV7DurableOperationIdFactory.java`처럼 바꾼다.
### 판단: 불변식을 어디 두나
+15 -20
View File
@@ -2,9 +2,9 @@
## 핵심
새 기능을 두는 모양은 셋이다. **업무 기능의 기본은 ① 계층 leaf 안 `<feature>` 패키지**다.
선택해서 켜고 끄는 플랫폼 기능만 ② 별도 `application-*` leaf로 만든다. ③ 한 leaf 수직 슬라이스는
지울 수 있는 샘플 전용이다. 생성 명령은 ①만 만든다.
새 기능을 두는 모양은 둘이다. **업무 기능의 기본은 ① 계층 leaf 안 `<feature>` 패키지**다.
선택해서 켜고 끄는 플랫폼 기능만 ② 별도 `application-*` leaf로 만든다. 한 leaf에 모든 계층을 두는
수직 슬라이스는 쓰지 않는다. 생성 명령은 ①만 만든다.
```text
① 계층 leaf 안 패키지 (기본)
@@ -13,21 +13,18 @@
② 기능 전용 leaf (capability)
application-<f> -> persistence-<f>, adapter:outbound:<f>, adapter:inbound:web-<f> -> composition:<f>-platform
app-bootstrap/build.gradle 에 runtimeOnly 한 줄
③ 한 leaf 수직 슬라이스 (샘플 전용)
sample-portfolio = domain + application + adapter + bootstrap 패키지
```
## 기준표
| 질문 | ① 계층 leaf 패키지 | ② 기능 leaf | ③ 수직 슬라이스 |
| --- | --- | --- | --- |
| 서비스마다 켜고 끌 수 있어야 하나 | 아니오 | **예** | — |
| 다른 서비스가 같은 기능을 라이브러리로 받나 | 아니오 | **예** | 아니오 |
| 한 줄 지워 기능을 통째로 빼야 하나 | 아니오(패키지 삭제) | **예**(`runtimeOnly` 한 줄) | 예(leaf 삭제) |
| leaf 단위 의존 방향 검사가 기능 안에도 걸리나 | 예(계층이 leaf) | 예 | **아니오**(ArchUnit 패키지 규칙에만 기댐) |
| 고칠 공용 파일 | 없음(+ imports 한 줄) | `modules.json`, `settings.gradle` 매핑, `app-bootstrap/build.gradle`, lockfile | `modules.json` |
| 예시 | 생성 명령 출력, `application-core/.../operation` | `application-notification`, `application-fileserver`, `application-objectstorage` | `sample-portfolio` |
| 질문 | ① 계층 leaf 패키지 | ② 기능 leaf |
| --- | --- | --- |
| 서비스마다 켜고 끌 수 있어야 하나 | 아니오 | **예** |
| 다른 서비스가 같은 기능을 라이브러리로 받나 | 아니오 | **예** |
| 한 줄 지워 기능을 통째로 빼야 하나 | 아니오(패키지 삭제) | **예**(`runtimeOnly` 한 줄) |
| leaf 단위 의존 방향 검사가 기능 안에도 걸리나 | 예(계층이 leaf) | 예 |
| 고칠 공용 파일 | 없음(+ imports 한 줄) | `modules.json`, `settings.gradle` 매핑, `app-bootstrap/build.gradle`, lockfile |
| 예시 | 생성 명령 출력, `application-core/.../operation` | `application-notification`, `application-fileserver`, `application-objectstorage` |
### 판단: ①과 ② 중 무엇인가
@@ -39,19 +36,18 @@
- **다시 볼 조건**: 파생 서비스가 둘 이상 생겨 같은 업무 기능을 공유하거나, application-core 컴파일·테스트
시간이 문제가 되면 ①을 ②로 옮긴다.
### 판단: ③을 써도 되나
### 판단: 한 leaf 수직 슬라이스를 써도 되나
- **기본값**: 쓰지 않는다. ③은 leaf 하나가 모든 계층에 의존해서 leaf 단위 방향 검사가 기능 안에서는
- **기본값**: 쓰지 않는다. leaf 하나가 모든 계층에 의존해서 leaf 단위 방향 검사가 기능 안에서는
아무것도 막지 못한다.
- **예외**: 통째로 지울 수 있어야 하는 샘플·데모. `sample-portfolio`가 그 예다. 샘플을 계층 leaf로 쪼개지
않는 이유는 "leaf 하나 지우면 끝"이라는 성질을 지키려는 것이다.
- **예외**: 없다. 이 모양이던 샘플 모듈은 매뉴얼과 생성 명령이 예시를 맡아 2026-11-07에 지웠다.
## ① 안의 패키지 규칙
| 계층 | 패키지 | 하위 패키지 |
| --- | --- | --- |
| domain | `dev.caskeleton.domain.<f>` | fake·계약은 testFixtures `dev.caskeleton.domain.<f>.testkit` |
| application | `dev.caskeleton.application.<f>` | 종류별 하위 패키지(`command`, `usecase`, `port`)를 만들지 않는다. 기능별 한 패키지(`sample-portfolio`도 2026-09-29에 이 배치로 옮겼다) |
| application | `dev.caskeleton.application.<f>` | 종류별 하위 패키지(`command`, `usecase`, `port`)를 만들지 않는다. 기능별 한 패키지 |
| outbound | `dev.caskeleton.adapter.outbound.<leaf>.<f>` | |
| inbound | `dev.caskeleton.adapter.inbound.web.<f>` | |
| bootstrap | `dev.caskeleton.bootstrap.autoconfigure.<f>` | `@AutoConfiguration`만(`BOOTSTRAP_AUTOCONFIGURE_STEREOTYPES_ARE_AUTO_CONFIGURATIONS`) |
@@ -73,4 +69,3 @@
- 업무 기능 = ① 계층 leaf 패키지. 생성 명령이 이 모양을 만든다.
- 켜고 끄는 플랫폼 기능 = ② 별도 leaf, capability 기준 7개.
- sample-portfolio는 기법 참고용이지 배치 예시가 아니다.
+13 -18
View File
@@ -31,7 +31,7 @@ use case ── tx.inWrite ──▶ XRepository (domain 포트)
adapter는 호출자 트랜잭션 밖의 호출을 거부하므로(아래 「트랜잭션 안에서만 쓴다」), 계약의
`inTransaction(Supplier)`을 재정의해 거기서 트랜잭션을 열고 커밋한다. 계약은 모든 저장소 호출을 그
hook으로 부른다. fake는 기본값(그냥 실행)을 쓴다.
예: `src/sample-portfolio/src/integrationTest/java/dev/caskeleton/sample/portfolio/adapter/outbound/persistence/repository/WorkLogRepositoryAdapterContractTest.java`.
예: `src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/operation/JpaDurableOperationStoreContractTest.java`.
5. adapter를 bean으로 등록하는 자동 설정을 쓰고, 기능의 `XConfig`에 `afterName`으로 그 순서를 적는다.
## 판단: 저장 adapter를 둘 leaf
@@ -44,7 +44,6 @@ use case ── tx.inWrite ──▶ XRepository (domain 포트)
("모듈을 아는 곳은 모듈 자신뿐")을 어기고, ② 그 leaf의 공개 API 기준선
(`docs/architecture/jpa-api-surface.txt`)과 엔티티 scan 목록(`PersistenceJpaConfig`,
`PersistenceEntityScanCoverageTest`)을 고쳐야 하며, ③ upstream 병합 충돌 면이 넓어진다.
sample은 자기 leaf 안에 adapter를 둔다(③ 수직 슬라이스라서).
- 새 leaf는 `modules.json` 등록, lockfile 생성, `app-bootstrap/build.gradle` 한 줄이 필요하다(10장).
## 엔티티 매핑
@@ -80,22 +79,22 @@ store는 자기 트랜잭션을 열지 않는다. 유스케이스가 연 트랜
- 중복 금지 → 유일성 제약/인덱스. 유스케이스의 사전 조회(`existsBy…`)는 빠른 거절일 뿐이다.
READ COMMITTED에서 두 요청이 모두 "없음"을 보고 둘 다 insert한다.
- adapter가 그 **이름 붙은 제약**의 위반만 잡아 기능 예외로 바꾼다. 다른 제약 위반은 그대로 둔다.
예: `src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/adapter/outbound/persistence/repository/PosterRepositoryAdapter.java`
(`DataIntegrityViolationException` → 제약 이름 확인 → `PosterTitleAlreadyExistsException` 409),
제약은 `src/sample-portfolio/src/main/resources/db/sample-migration/V8_1__poster_title_unique.sql`.
순서는 `DataIntegrityViolationException`을 잡는다 → 원인의 제약 이름이 그 제약인지 본다 → 맞으면
기능 예외(예: `TitleAlreadyExistsException`, 409)를 던지고, 아니면 다시 던진다. 템플릿 코드에는 이
모양의 예가 없다. 확인은 아래 공유 계약 테스트와 동시성 테스트로 한다.
- **충돌을 바꾸는 곳은 하나다.** 업무 규칙 충돌(같은 제목)은 포트 옆 domain 패키지의 예외 타입이고,
포트가 `@throws`로 선언하고 adapter가 던진다. 유스케이스의 사전 조회도 같은 타입을 던져 두 경로가 같은
409가 된다. application 예외를 domain 포트가 Javadoc으로만 가리키면 fake·mock은 그 약속을 지킬 수 없다.
기술 충돌(버전 불일치·교착)은 adapter가 프레임워크 예외 그대로 두고 아래 `PersistenceExceptionTranslator`가
`DB_*` 코드로 바꾼다(WorkLog의 `ObjectOptimisticLockingFailureException` → `DB_OPTIMISTIC_CONFLICT`).
`DB_*` 코드로 바꾼다(`ObjectOptimisticLockingFailureException` → `DB_OPTIMISTIC_CONFLICT`).
- 그 약속은 포트 소유자 testFixtures의 공유 계약 테스트로 고정한다. fake와 adapter가 같은 계약을 상속한다.
예: `PosterRepositoryContract`(`InMemoryPosterRepository`, `PosterRepositoryAdapterContractTest`).
예: `DurableOperationStoreContract`(`InMemoryDurableOperationStore`, `JpaDurableOperationStoreContractTest`).
- 여러 인스턴스가 집는 작업 → `FOR UPDATE SKIP LOCKED`는 **트랜잭션 안에서**, 그리고 lease(만료 시각)와
fence 값을 함께 저장한다. 예: `ReconciliationJobStorePort.claimDue`(application-notification),
gRPC operation ledger의 claim.
- 수정 충돌 → 버전 열(낙관적 잠금). 예: `UpdateWorkLogUseCase`의 version 비교와 `@Version`.
- 수정 충돌 → 버전 열(낙관적 잠금). 예: `DurableOperationEntity`(persistence-jpa)의 `@Version` 열 `row_version`.
- **예외**: DB가 볼 수 없는 규칙(외부 시스템 상태)은 분산 락(`DistributedLockPort`)이나 멱등성 키(05장).
- 동시성 테스트는 실 DB lane에서 동시 요청 N개 → 행 1개를 단언한다(sample `integrationTest` 참고).
- 동시성 테스트는 실 DB lane에서 동시 요청 N개 → 행 1개를 단언한다.
## 기술 실패는 공통 코드로 나간다
@@ -110,14 +109,11 @@ SQLState 표를 복사하지 않는다.
```text
템플릿 운영 스트림 classpath:db/migration/postgresql V1 … V19 … (upstream이 계속 늘린다)
capability 스트림 db/migration/jpa/<capability> 각자 history table
샘플 스트림 db/sample-migration flyway_sample_schema_history
서비스 스트림(권장) db/migration/<service> flyway_<service>_schema_history
```
- **고르는 기준**: upstream 템플릿을 계속 받을 것인가.
- **기본값**: 서비스 마이그레이션은 **자기 위치 + 자기 history table** 스트림에 둔다. 모양은
`SamplePostgreSqlPersistenceConfig.sampleMigrationStrategy`
(`src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/bootstrap/persistence/SamplePostgreSqlPersistenceConfig.java`)와
`NotificationSchemaStream`(persistence-notification). 그러면 번호가 템플릿 스트림과 독립이라 V1부터 쓴다.
자기 스트림의 Flyway는 `Flyway.configure()`가 아니라 `FlywaySchemaPolicy.configure()`(persistence-jpa)로
만든다. Flyway의 PostgreSQL 잠금을 세션에 두어야 `CREATE INDEX CONCURRENTLY` 마이그레이션이 끝난다.
@@ -128,21 +124,20 @@ capability 스트림 db/migration/jpa/<capability> 각자 histor
겹친다. 어쩔 수 없으면 upstream이 쓰지 않을 큰 번호대를 정해 문서에 적는다.
- 이미 적용된 파일은 고치지 않는다. 고치면 체크섬 불일치로 기동이 멈추고, `repair`는 쓰지 않는다
(`docs/jpa/migration-guide.md`).
- 같은 스트림 안에서 기존 두 버전 사이에 끼워야 하면 소수 버전(`V8_1`)을 쓴다. 샘플 테스트 일부가 운영
스트림과 샘플 스트림을 한 목록으로 합치는데, 정수 V9 이상은 운영이 이미 쓰고 있어서 2026-11-01 샘플에
포스터 제목 유일 제약을 더할 때 `V8_1`을 골랐다.
- 기존 데이터가 새 제약을 어기면 마이그레이션이 이유를 남기고 멈추게 쓴다(`V8_1`의 `DO $$` 블록). 조용히
- 같은 스트림 안에서 기존 두 버전 사이에 끼워야 하면 소수 버전(`V8_1`)을 쓴다. 두 스트림을 한 목록으로
합쳐 검사하는 테스트가 있으면, 다른 스트림이 이미 쓴 정수 번호를 피하려고 이렇게 끼운다.
- 기존 데이터가 새 제약을 어기면 마이그레이션이 이유를 남기고 멈추게 쓴다(`DO $$` 블록의 `RAISE EXCEPTION`). 조용히
지우지 않는다.
- 운영 중인 테이블을 잠그는 문장(`ALTER TABLE`, `CONCURRENTLY` 없는 `CREATE INDEX`, `UPDATE`·`DELETE`, 기존
테이블을 가리키는 `REFERENCES`, trigger 만들기·지우기 등 — 전체 목록은 `docs/jpa/migration-guide.md`)이 있으면
그 앞에 `SET LOCAL lock_timeout = '5s';`를 둔다(`V8_1`, `V22`). 값은 0이 아니어야 하고,
그 앞에 `SET LOCAL lock_timeout = '5s';`를 둔다(`V22`). 값은 0이 아니어야 하고,
`executeInTransaction=false` 마이그레이션에서는 `SET LOCAL`이 효과가 없으니 잠그는 문장을 거기 두지 않는다. Flyway가
스스로 트랜잭션 밖에서 돌리는 문장(`VACUUM`, `CREATE INDEX CONCURRENTLY` 등 — 목록은 같은 가이드)이 하나라도 있는 파일도
트랜잭션 밖에서 돌므로, 그런 문장은 따로 한 파일에 둔다. `VACUUM FULL`처럼 트랜잭션 안에서 돌 수 없는 잠금 문장은
상한을 걸 수 없으니 마이그레이션에 두지 않고 운영 절차로 돌린다. 상한이 없으면 그 테이블을 건드린 열린
트랜잭션 하나(`ALTER TABLE`이면 읽기만 한 것도) 뒤에서 마이그레이션이 끝없이 기다리고, 그동안 뒤에 온 그
테이블의 쓰기(`ALTER TABLE`이면 읽기까지)가 모두 마이그레이션 뒤에 줄을 선다. 상한이 있으면 5초 뒤 실패·롤백되고 새 버전이 뜨지 않을 뿐이다. 자기 스트림에도
`SampleMigrationLockWaitTest`처럼 `LockWaitMigrationInspector`(persistence-jpa testkit) 검사를 둔다
`MigrationLockWaitTest`(persistence-jpa)처럼 `LockWaitMigrationInspector`(persistence-jpa testkit) 검사를 둔다
(`docs/jpa/migration-guide.md` "Bound the lock wait").
## 지금 이해하면 되는 것
+3 -2
View File
@@ -40,8 +40,9 @@ DB 커밋 중 연결 끊김 ─────────────────
5. 저장소 provider를 고른다: `app.capabilities.idempotency.provider` = `postgresql` 또는 `redis`
(기본 `disabled`). 운영에서 in-memory 금지.
예: `src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/adapter/inbound/web/` 의
`PosterImagePublicationController`(키 헤더 검증), 유스케이스 쪽은 sample `application/posterimage`.
예: 키 헤더 검증은 `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/http/IdempotencyKeyHeader.java`,
executor 조립과 실제 PostgreSQL 저장소 왕복은 `PostgreSqlIdempotencyProviderIntegrationTest`(app-bootstrap
`integrationTest`)다. KEYED 유스케이스를 HTTP부터 끝까지 이은 업무 기능 예는 템플릿에 없다.
## 클라이언트에게 무엇을 약속하나
+3 -5
View File
@@ -26,9 +26,7 @@ gRPC/GraphQL/WebSocket: 같은 ApiErrorCarrier를 자기 status 모양으로
- **기본값**: application 기능 패키지의 `XErrorCode implements ApiErrorCode` enum + 예외가
`ApiErrorCarrier` 구현. 전송마다 핸들러를 만들 필요가 없다. 생성 명령 출력이 이 모양이다
(`<F>ErrorCode`, `<F>NotFoundException`, `<F>RejectedException`).
- **예외**: 한 전송에서만 의미가 있는 실패(HTTP 헤더 형식 등)는 그 전송 adapter에 둔다. sample은 기능
코드를 web 패키지(`PortfolioErrorCode`, `DomainExceptionHandler`)에 두는데, 한 leaf 수직 샘플이라
가능한 모양이다. 따라 하지 않는다.
- **예외**: 한 전송에서만 의미가 있는 실패(HTTP 헤더 형식 등)는 그 전송 adapter에 둔다.
## 판단: 어떤 예외 타입으로 던지나
@@ -58,8 +56,8 @@ gRPC/GraphQL/WebSocket: 같은 ApiErrorCarrier를 자기 status 모양으로
- 템플릿 운영 코드: `OperationalError` + `docs/registries/error-codes.yaml`을 같은 변경에서 고친다.
`ErrorCodeRegistryMappingTest`(app-bootstrap)가 status 일치를 검사한다.
- 서비스 기능 코드: 그 registry에 넣지 않는다(registry 머리말 "Product/fork ApiErrorCode enums own local
registries"). 서비스 자기 registry를 만들고 같은 모양의 대조 테스트를 둔다. 예:
`src/sample-portfolio/src/test/java/dev/caskeleton/sample/portfolio/adapter/inbound/web/error/PortfolioErrorCodeRegistryMappingTest.java`.
registries"). 서비스 자기 registry를 만들고 같은 모양의 대조 테스트를 둔다. 모양은 위
`ErrorCodeRegistryMappingTest`(`src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/ErrorCodeRegistryMappingTest.java`)다.
## 지금 이해하면 되는 것
+2 -2
View File
@@ -25,8 +25,8 @@
| 프록시 가능 | `src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/authz/RequiresPermissionProxyabilityTest.java` |
검사 자동 설정은 인증 체인(`WebSecurityAutoConfiguration`)과 **분리**되어 있다. 서비스가 자기 인증
방식으로 인증 체인을 바꿔도 권한 검사는 꺼지지 않는다(2026-11-01부터. 전에는 샘플이 인증 체인 자동 설정을
빼자 권한 검사도 함께 빠졌다).
방식으로 인증 체인을 바꿔도 권한 검사는 꺼지지 않는다(2026-11-01부터. 전에는 인증 체인 자동 설정을 빼면
권한 검사도 함께 빠졌다).
### 지켜야 할 것 셋
+1 -1
View File
@@ -62,7 +62,7 @@ lane으로 선언하고 단계를 지정한다. 선언은 `ca.strict-test-lane`(
| 성능·부하 | performance 범주 | `performanceCheck` |
| 외부 입력 필요(자격증명 등) | `explicitOnly(reason)` | 어떤 집계에도 안 들어가고 이유가 출력된다 |
예: `src/sample-portfolio/build.gradle`의 `strictTestLanes { lane('integrationTest') { integration() … } }`,
예: `src/app-bootstrap/build.gradle`의 `strictTestLanes { lane('integrationTest') { integration() … } }`,
`src/app-bootstrap/build.gradle`의 `publicPathSnapshotTest`(`mainStage()`).
### 판단: 새 테스트를 어느 lane에
+6 -6
View File
@@ -23,15 +23,15 @@ DB 저장과 broker 발행을 따로 하면(dual write) 둘 중 하나만 성공
## 순서
1. 계약을 정한다: 계약 id(`<service>.<aggregate>.<event>`), 버전, payload record, JSON schema 파일과 해시.
예: `src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/application/worklog/WorkLogReservedContractContribution.java`,
`src/sample-portfolio/src/main/resources/contracts/messaging/portfolio.worklog.reserved/v1.schema.json`(+ `.sha256`).
예: `src/application-core/src/main/java/dev/caskeleton/application/operation/DurableOperationSubmittedContract.java`,
`src/application-core/src/main/resources/contracts/messaging/durable-operation.submitted/v1.schema.json`(해시는 계약 클래스 안).
2. payload record(`IntegrationPayload`)를 만든다.
3. 유스케이스의 `tx.inWrite` 안에서 저장 뒤 draft → encode → append. 예:
`CreateWorkLogUseCase`(sample)와 그 헬퍼 `PortfolioEventOutbox`.
`SubmitDurableOperationUseCase`(application-core `operation`).
4. 계약 contribution을 조립에서 `@Bean`으로 등록한다. encoder는 컨텍스트의 계약 bean으로 만들어진다.
등록을 빠뜨리면 append 때 실패한다. 예: `DurableOperationAutoConfiguration.durableOperationSubmittedContract()`.
5. 테스트: 계약 contribution 테스트(해시 고정), 유스케이스가 append했는지(`InMemoryOutboxStore`),
소비자 중복 제거 계약(sample `WorkLogReservedConsumerDedupeContractTest`).
소비자가 있으면 같은 event id를 두 번 받아도 효과가 한 번인지 보는 중복 제거 계약.
6. schema를 출시한다: `src/test/resources/contracts/released-payload-schemas.sha256`에 새 version 파일의
해시를 한 줄 더한다. 출시한 version 파일은 고치지 않는다 — 바뀌면 `ReleasedPayloadSchemaContract`
테스트가 실패한다. 필드를 바꾸는 변경은 새 version으로 낸다. 절차: `src/application-core/README.md`
@@ -44,7 +44,7 @@ DB 저장과 broker 발행을 따로 하면(dual write) 둘 중 하나만 성공
- **고르는 기준**: 같은 서비스 안에서 이 사실에 반응하는 코드가 있는가.
- **기본값**: 통합 이벤트만. 유스케이스가 저장 뒤 바로 payload를 만든다.
- **예외**: aggregate 안에서 일어난 사실을 여러 유스케이스가 같은 방식으로 내보내면 domain
`@DomainEvent` record를 두고 유스케이스가 그것을 payload로 옮긴다(sample `WorkLogReserved`).
`@DomainEvent` record를 두고 유스케이스가 그것을 payload로 옮긴다.
### payload에 무엇을 넣나
@@ -57,7 +57,7 @@ draft는 `IntegrationEventDrafts.draft(contract, eventId, aggregate, order, occu
만든다(`src/application-core/src/main/java/dev/caskeleton/application/messaging/event/IntegrationEventDrafts.java`).
계약 id·payload 버전·목적지는 계약에서 오고, 기능이 정하는 것은 aggregate·순서·payload뿐이다.
`new IntegrationEventDraft<>(…)`를 직접 쓰면 빌드가 막는다(`INTEGRATION_EVENT_DRAFTS_ARE_BUILT_BY_THE_SHARED_HELPER`).
예: sample `PortfolioEventOutbox`, `SubmitDurableOperationUseCase`.
예: `SubmitDurableOperationUseCase`.
- event id: 정규 소문자 UUIDv7, 소비자 중복 제거 키. draft(`IntegrationEventDraft`)가 다른 값(대문자,
v4, `event-1` 같은 문자열)을 거부하므로 업무 쓰기에서 바로 실패한다 — 커밋된 뒤 relay에서 DEAD가 되지
+5 -5
View File
@@ -55,13 +55,13 @@
## 따라 할 예시는 하나
예시가 셋(sample-portfolio 수직, onboarding fixture, durable operation)이라 어느 것을 베끼느냐에 따라
배치가 달라졌다(2026-11-01 성숙도 리뷰). 이제 **새 업무 기능의 예시는 생성 명령의 출력 하나**다.
예시가 셋(한 leaf에 모든 계층을 둔 샘플 모듈, onboarding fixture, durable operation)이라 어느 것을 베끼느냐에 따라
배치가 달라졌다(2026-11-01 성숙도 리뷰). 이제 **새 업무 기능의 예시는 생성 명령의 출력 하나**다. 샘플 모듈은
2026-11-07에 지웠다.
| 코드 | 역할 | 따라 하나 |
| --- | --- | --- |
| `scripts/new-feature.sh` 출력 | 계층 leaf에 나눈 업무 기능 | **이것을 따른다** |
| `src/sample-portfolio` | 한 leaf에 모든 계층을 둔 지울 수 있는 샘플. 개별 기법(조건부 PATCH, 페이지, outbox, DB 유일성 제약)의 참고 | 기법만 본다. 배치는 따르지 않는다 |
| `src/app-bootstrap/src/test/java/dev/caskeleton/onboarding/**` | ArchUnit 규칙이 새 기능 모양에 적용되는지 확인하는 테스트 fixture | 따르지 않는다 |
| `application-core/.../operation` + `DurableOperationAutoConfiguration`(composition:durable-operation) | 템플릿 플랫폼 기능 | 조립 모양(`@ConditionalOnBean` + 유스케이스 `@Bean`)만 본다 |
@@ -74,12 +74,12 @@
| Envelope는 null 필드를 내보내지 않는다 | `docs/web/http-contract.md` 1절 | 06 |
| 처리 중 409 `IDEMPOTENT_IN_FLIGHT`는 `retryable=true` + `Retry-After: 2`, 같은 키로 재전송 | `docs/web/http-contract.md` 2절 | 05 |
| 커밋 중 연결이 끊기면 재시도 가능이 아니라 결과 불명(`DB_COMPLETION_UNKNOWN`, 500) | `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/failure/PersistenceExceptionTranslator.java`, `docs/adr/ADR-JPA-003-completion-unknown.md` | 05 |
| 중복 규칙은 조회 후 insert가 아니라 DB 유일성 제약, 위반은 같은 409로 변환 | `src/sample-portfolio/src/main/resources/db/sample-migration/V8_1__poster_title_unique.sql`, `PosterRepositoryAdapter` | 04 |
| 중복 규칙은 조회 후 insert가 아니라 DB 유일성 제약, 위반은 같은 409로 변환 | 04장 「중복·경쟁은 DB가 막는다」(템플릿 코드에 예 없음) | 04 |
| 여러 인스턴스가 집는 작업은 lease 있는 claim | `ReconciliationJobStorePort.claimDue`(application-notification) | 04 |
| 양방향 연관관계 금지를 ArchUnit으로 | `JpaArchitectureRules.associationsAreMappedFromOneSideOnly()` | 04 |
| store는 호출자 트랜잭션을 요구한다 | `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/transaction/CallerTransaction.java` | 04 |
| `@RequiresPermission` 검사는 인증 체인과 분리된 자동 설정 | `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/mvc/autoconfigure/WebMethodSecurityAutoConfiguration.java` | 07 |
| JWT audience 필수, 자기 client role만 | `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/auth/JwtDecoderConfig.java`, `docs/runbooks/auth-audience-mismatch.md` | 07 |
| strict lane은 반드시 어떤 단계에 속한다 | `verifyStrictLaneStages`(`src/build.gradle` `strictLaneStages`) | 08 |
| 샘플 마이그레이션은 별도 history table, 번호는 운영과 겹치지 않게 | `SamplePostgreSqlPersistenceConfig`, `V8_1__…` | 04 |
| 서비스 마이그레이션은 별도 history table, 번호는 운영과 겹치지 않게 | `NotificationSchemaStream`(persistence-notification) | 04 |
| 재시도 가능한 broker 거부는 DEAD가 아니라 재시도 | `docs/runbooks/outbox-dead-letter.md` | 09 |
+4
View File
@@ -21,6 +21,10 @@ runtime이 admin 자격 증명을 아예 보유하지 않으므로, 침해된 ha
- broker authentication 활성
- topology auto-create 비활성
broker 인증서는 `subjectAltName`에 접속 이름을 가져야 한다. hostname verification은 SAN을 보므로, SAN이
없는 인증서는 실패하는 것이 맞다. 검사를 끄지 않는다. 키와 인증서는 배포 환경의 PKI가 발급해 실행 때
마운트하고, repo에 두지 않는다.
Kafka는 추가로 `enable.idempotence=true`, `acks=all`,
`max.in.flight.requests.per.connection <= 5`, consumer auto-commit 금지.
+1 -1
View File
@@ -27,7 +27,7 @@
> `modules.json`은 messaging leaf의 `gradle_path`와 허용 의존성을 관리하지만
> `runtime_memberships` 필드는 없다. 실제 런타임 편입은 `app-bootstrap`의 Gradle 의존성과 starter /
> auto-configuration 경로가 결정한다. 아래 등급은 "무엇이 증명되었는가"를 말하며 런타임 편입 여부와
> 같은 축이 아니다. 자세한 composition/cutover 상태는 `src/messaging/CLAUDE.md`가 소유한다.
> 같은 축이 아니다. 자세한 composition/cutover 상태는 `src/platforms/messaging/CLAUDE.md`가 소유한다.
## 브로커 등급
+1 -1
View File
@@ -13,7 +13,7 @@ enables the capability; construction is refused otherwise.
| Topology | A real sharded cluster. A replica set cannot exercise routing. |
| Server | MongoDB 7.0 or 8.0. |
| Privilege | `MongoPrincipalRole.SHARD_ADMIN` for the admin plane; the application role is unchanged. |
| 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/config/mongodb/release-contracts.json`; promoting it needs the lane, its required class, and protected-environment evidence to exist first. |
| 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. |
## Shard key
+1 -1
View File
@@ -68,7 +68,7 @@ nothing in this repository has executed against 7.2 or 8.2.
### What the standalone ACL run established
`RedisTopologyContractTest` runs the four accounts in `infra/redis-sdk/acl` against a live server and
`RedisTopologyContractTest` runs the four accounts in `compose/redis/acl` against a live server and
asserts that each `CommandAccess` level grants exactly what the command policy catalog says it may
issue. Writing it found five defects that no amount of reading the files would have surfaced:
+1 -1
View File
@@ -42,7 +42,7 @@ actually run.
## 5. Topology suite
Run the standalone, Sentinel, and Cluster lanes declared in `infra/redis-sdk/`. A version is
Run the standalone, Sentinel, and Cluster lanes declared in `src/adapter/outbound/redis-sdk/compose/`. A version is
certified by the lane passing, not by the version number being newer.
*Why:* failover certainty and cross-slot behaviour are the two things the in-memory fixture cannot
+4 -4
View File
@@ -2031,7 +2031,7 @@ env_keys:
# secret://<acl-account>@<source>/<name> form as the application reference. Unset, scripts run
# as the application account and startup logs a warning saying so. The Compose Redis lanes use
# secret://ca-skeleton-application-advanced@environment/REDIS_LANE_ADVANCED_PASSWORD, a fixture
# account of infra/redis-sdk/acl/lane-fixture-accounts.acl.
# account of compose/redis/acl/lane-fixture-accounts.acl.
property: app.redis.authentication.advanced-credential-reference
owner_module: adapter-outbound-cache-redis
type: string
@@ -2074,7 +2074,7 @@ env_keys:
# <name>. Without the account part the client authenticates as `default`, which a hardened
# Redis turns off. The Compose Redis lanes use
# secret://ca-skeleton-application@environment/REDIS_LANE_APPLICATION_PASSWORD, a fixture
# account of infra/redis-sdk/acl/lane-fixture-accounts.acl.
# account of compose/redis/acl/lane-fixture-accounts.acl.
property: app.redis.authentication.credential-reference
owner_module: adapter-outbound-cache-redis
type: string
@@ -2631,8 +2631,8 @@ env_keys:
required_test: cache-contract:redis-soft-hard-ttl-order
- name: APP_CACHE_REDIS_TTL_JITTER
# DEPRECATED 2026-11-02: no settings class binds it. Its only reader was a block in
# sample-portfolio's application.yml that nothing bound either (07-10), removed with it.
# DEPRECATED 2026-11-02: no settings class binds it. Its only reader was a block in the
# sample module's application.yml that nothing bound either (07-10), removed with it.
# Kept so a deployment still setting it is told it does nothing.
deprecated_orphaned: true
removal_deadline: 2027-02-28
+1 -1
View File
@@ -11,7 +11,7 @@
# - prod profile에서 `__LOCAL_DEV_` prefix 발견 시 startup fail
# (feature-secrets-config-source-contract 2026-05-22).
# - prod profile에서 비밀값이 `fixture-`로 시작하면(이 저장소에 적힌 lane fixture 비밀번호 —
# infra/redis-sdk/acl, compose lane의 REDIS_LANE_*) 같은 이유로 startup fail (review 2026-11-03
# compose/redis/acl, compose lane의 REDIS_LANE_*) 같은 이유로 startup fail (review 2026-11-03
# RR-07-04). 비밀값만 본다: 이 파일의 `secret` 행(SecretSourceValidator.CLASSIFIED_SECRETS,
# SecretsClassificationRegistryTest가 1:1로 묶음), 모듈이 기여한 비밀, `secret://…/<VAR>` 참조가
# 가리키는 변수. HOSTNAME·앱 이름 같은 비밀이 아닌 값은 보지 않는다 (review 2026-11-04 RR2-04-01).
+2 -2
View File
@@ -10,7 +10,7 @@
- 대응하는 Test 태스크 없음
- 공통 스키마 validator 없음
따라서 `config/messaging/readiness-cards.yaml`의 카드는 모두 `maturity: not-implemented`다.
따라서 `src/adapter/outbound/messaging/release/readiness-cards.yaml`의 카드는 모두 `maturity: not-implemented`다.
유일하게 `implemented-candidate`였던 `json-schema-envelope.v1`은 그 구현(adapter messaging의
`JsonSchemaIntegrationEventEncoder`와 `verifyMessagingJsonSchemaV1`)을 2026-09-25에 삭제하면서
`not-implemented`로 내렸다. 남은 evidence producer는 `verifyMessagingContracts` 하나다.
@@ -41,7 +41,7 @@ verifyMessagingTargetBindingPreflight
1. 각 시나리오를 실제로 실행하는 Test 태스크.
2. 그 실행 결과(JUnit XML)에서 payload-free manifest를 만드는 producer.
3. `config/messaging/evidence/build-evidence-manifest-v1.schema.json`으로 그 manifest 바이트를
3. `src/adapter/outbound/messaging/release/evidence/build-evidence-manifest-v1.schema.json`으로 그 manifest 바이트를
검증하는 단계(build-tools `VerifyMessagingEvidenceTask`가 쓰고 바로 검증한다).
4. 위 셋이 모두 생긴 다음에 `verifyMessaging<Scenario>R2` 태스크 등록.
+1 -1
View File
@@ -131,7 +131,7 @@ status: active
between them and is claimed again by a new request is deleted while that request runs, and
the next request with the key runs the work a second time (re-review 2026-11-04 RR4-03-02).
The program below deletes the key only while its `state` is `ABANDONED`. The application
accounts are denied `EVAL` (`infra/redis-sdk/acl/README.md`), so load it and run it by the
accounts are denied `EVAL` (`compose/redis/acl/README.md`), so load it and run it by the
digest `SCRIPT LOAD` prints, as the service runs its own scripts:
<!-- runbook-redis: idempotency-delete-abandoned -->
+1 -1
View File
@@ -50,7 +50,7 @@ status: stub
- 의존성 지연이 근본 원인이면 해당 의존성 오너에게 escalate
- 종료 예산은 차례로 더한 값이다: 웹 drain(`APP_SERVER_SHUTDOWN_TIMEOUT`, 기본 30s)이 끝난 뒤 async 대기 19s,
합계 49s에 preStop(5s)과 여유를 더한다. k8s `terminationGracePeriodSeconds`가 이보다 작으면(예: 기본 30s)
async 대기 중 SIGKILL이다. compose는 60s(`docker-compose.yml` `stop_grace_period`, 합계는
async 대기 중 SIGKILL이다. compose는 60s(`compose.yaml` `stop_grace_period`, 합계는
`DeveloperExperienceContractTest`가 검사). 정합 이슈면 플랫폼/런타임 오너에게 escalate
## 6. Recovery / Verification
+1 -1
View File
@@ -22,7 +22,7 @@ status: active
1. Stop rollout and keep the failed revision out of readiness. Do not route traffic to a partially
migrated instance.
2. Identify the exact stream from `src/config/jpa/readiness-cards.yaml`. Each stream has an
2. Identify the exact stream from `src/adapter/outbound/persistence-jpa/release/readiness-cards.yaml`. Each stream has an
independent `location` and `history-table`; do not infer ownership from a broad
`classpath:db/migration` scan.
3. From a privileged migration session, capture the stream state before changing anything:
+2 -2
View File
@@ -152,7 +152,7 @@ rolling 중 옛 버전이 방금 쓴 번호(floor보다 초당 10⁶씩 큰 벽
소비자는 그 사이 새 이벤트를 버린다. 그래서 **tenant scope를 바꾸는 배포는 rolling으로 하지 않는다**: 옛 버전
인스턴스를 모두 멈춘 뒤(옛·새 버전이 함께 쓰는 구간 없이) 새 버전을 띄운다.
tenant scope를 바꾼 서비스(샘플은 `portfolio` → 단일 scope)는 배포 전에 옛 scope의 미발행 행이
tenant scope를 바꾼 서비스(예: 기능별 scope → 단일 scope)는 배포 전에 옛 scope의 미발행 행이
없는지 확인한다. 옛 scope 행과 새 scope 행은 서로 다른 aggregate로 보여 claim gate가 서로를 막지 않고,
partition key도 달라 다른 partition으로 간다.
@@ -252,7 +252,7 @@ COMMIT;
```
Step 1을 다시 돌려 0행이면 배포한다. 정리와 배포 사이에 옛 버전이 새 중복을 만들 수 있다(벽시계로
순서 번호를 만든 샘플 코드가 그 원인이었다). 그래도 V21은 실패하고 롤백될 뿐이니 Step 1부터 다시 한다.
순서 번호를 만든 옛 코드가 그 원인이었다). 그래도 V21은 실패하고 롤백될 뿐이니 Step 1부터 다시 한다.
`outbox_event_v21_duplicates`는 확인이 끝나면 지운다.
확인 쿼리, 정리 SQL, Step 0의 인덱스 SQL은 이 문서에서 그대로 읽어 실제 PostgreSQL에서 실행하는
File diff suppressed because one or more lines are too long
+1 -1
View File
@@ -2,7 +2,7 @@
The Advanced capabilities live in their own leaf, `adapter:inbound:web-advanced`
(`src/adapter/inbound/web-advanced`, package `dev.caskeleton.adapter.inbound.web.advanced`). No
default composition carries it: `app-bootstrap` and `sample-portfolio` do not depend on it. A
default composition carries it: `app-bootstrap`은 이 leaf에 의존하지 않는다. A
service that wants one of these capabilities adds the leaf as `implementation` in its own adapter
leaf and calls the types directly.
+3 -2
View File
@@ -69,8 +69,9 @@ than silently absorbed.
## 5. Sample application
The design's `examples/web-platform-sample` is the existing `sample-portfolio` leaf, which already
carries the OpenAPI drift gate and the contract lanes the design's sample is specified to provide.
설계의 `examples/web-platform-sample`에 해당하는 모듈은 없다. 그 역할을 하던 샘플 leaf는 2026-11-07에
지웠고, 그 안의 OpenAPI 드리프트 검사와 실서버 계약 lane도 함께 사라졌다. 예시는 `docs/manual/`과
`scripts/new-feature.sh` 출력이 맡는다.
## 6. Idempotency: the design's store SPI is already owned by `application-core`
+3 -3
View File
@@ -49,13 +49,13 @@ design-docs `conventions/delegation-loop.md` 3절 순서대로 한다: 크기
| 영역 | 경로 |
| --- | --- |
| core·application | `src/domain-core`, `src/application-*`, `src/shared-contract` |
| inbound 전송 | `src/adapter/inbound/*`, `src/grpc/*`·`src/grpc-advanced/*`(optional 빌드) |
| inbound 전송 | `src/adapter/inbound/*`, `src/platforms/grpc/*`·`src/platforms/grpc-advanced/*`(optional 빌드) |
| persistence | `src/adapter/outbound/persistence-*`, 마이그레이션 |
| outbound capability | 그 밖의 `src/adapter/outbound/*`, 멱등성 store |
| messaging | `src/messaging/*`, `src/adapter/outbound/messaging` |
| messaging | `src/platforms/messaging/*`, `src/adapter/outbound/messaging` |
| bootstrap·build·CI | `src/app-bootstrap`, `src/composition/*`, `src/build-logic`, `src/build.gradle`, `.github/` |
| 보안(영역을 가로질러) | 인증·인가 체인, 비밀, 공개 경로 |
| 샘플·문서 | `src/sample-portfolio`, `docs/` |
| 문서 | `docs/` |
두 세션이 동시에 만지면 손으로 풀어야 하는 파일이다. 한 세션만 맡기거나, 총괄이 합칠 때 직접 고친다.
+3 -3
View File
@@ -23,7 +23,7 @@
- 업무 기능 하나는 보통 중간이다: 계층 leaf 여러 곳에 파일이 생기지만 판단은 매뉴얼이 정해 둔 범위 안이다.
- 큼: 새 capability 모듈, 새 leaf, 새 공개 계약, 파생 서비스가 따라 고쳐야 하는 변경. 큰 일은 설계와 소유자 검토가 먼저다([research-design.md](research-design.md)).
- 선행 사례는 생성 명령의 출력 하나다. `src/sample-portfolio`는 개별 기법(조건부 PATCH, 페이지, outbox, DB 유일 제약)의 참고일 뿐 배치를 따라 하지 않는다.
- 선행 사례는 생성 명령의 출력 하나다. 개별 기법의 예시는 `docs/manual/`이 실제 코드(fileserver, durable operation)로 가리킨다.
- 스킬: 설계가 바뀌면 `superpowers:brainstorming`, 여러 단계면 `superpowers:writing-plans`, 구현은 `superpowers:test-driven-development`.
## 4. 절차
@@ -51,7 +51,7 @@
## 6. 하지 말 것
- `AGENTS.md` HARD-STOP을 어기지 않는다. 특히 controller가 repository를 부르거나, inbound DTO가 application으로 들어가거나, 업무 규칙이 mapper·filter·설정에 들어가는 것.
- `src/sample-portfolio`의 배치(한 leaf에 모든 계층)를 따라 하지 않는다. onboarding 테스트 fixture도 따라 하지 않는다.
- 한 leaf에 모든 계층을 두지 않는다. onboarding 테스트 fixture도 따라 하지 않는다.
- 업무 코드를 템플릿 패키지에 넣지 않는다.
- 저장 adapter를 `persistence-jpa` leaf 안에 만들지 않는다. 서비스 전용 persistence leaf에 둔다.
- 한 단계가 다른 leaf나 계층을 고쳐야 하면 범위를 조용히 넓히지 않는다. 거기서 멈추고 설계를 다시 본다(7절).
@@ -74,6 +74,6 @@
## 9. 자주 하는 실수
- 샘플을 베껴 한 leaf에 모든 계층을 둔다. 생성 명령의 출력을 따른다.
- 한 leaf에 모든 계층을 둔다. 생성 명령의 출력을 따른다.
- 생성 명령을 노트북에서 기본 옵션으로 돌려 Gradle이 노트북에서 돈다. `--no-format`을 쓴다.
- 역할 → 권한 매핑을 빠뜨려 쓰기 API가 모든 요청에 403이다. `docs/manual/07-authorization.md`를 본다.
+1 -1
View File
@@ -59,7 +59,7 @@ git worktree remove ~/workspace/<작업 이름>
- 로그는 desktop `~/<작업 이름>-logs/`에 남기고, 보고에 그 desktop 경로와 rc를 쓴다. 같은 worktree의 다음 실행이 결과 XML을 덮어쓰니, 명령이 끝날 때마다 그 태스크의 `build/test-results/<태스크>/`를 로그 폴더로 복사한다(세는 법은 [reference/gates.md](reference/gates.md) 4절).
- RED 확인용 임시 worktree도 같은 방법으로 만들고 끝나면 지운다.
- workflow job이 도구를 내려받아 설치하는 단계(`curl … | sh`, setup action)는 desktop에서 따라 하지 않는다. 소유자 기계를 바꾸는 일이다. 이미 설치된 도구로만 돌리고, 없으면 못 돌림으로 적는다.
- compose를 띄웠으면 지우기 전에 `docker compose … down`을 한다. bind mount 폴더(`docker-compose.dev.yml`의 `tmp/heap-dumps`)는 Docker가 root로 만들어 `git worktree remove`가 Permission denied로 실패한다. compose가 이미 받은 이미지(`docker-compose.infra.yml`의 `redis:7.4`)로 폴더를 지운 뒤 다시 지운다: `docker run --rm --pull=never -v "$PWD/tmp:/t" redis:7.4 rm -rf /t/heap-dumps`.
- compose를 띄웠으면 지우기 전에 `docker compose … down`을 한다. bind mount 폴더(dev lane overlay `src/app-bootstrap/compose-lanes/dev.yaml`의 `tmp/heap-dumps`)는 Docker가 root로 만들어 `git worktree remove`가 Permission denied로 실패한다. compose가 이미 받은 이미지(`compose.yaml`의 `redis:7.4`)로 폴더를 지운 뒤 다시 지운다: `docker run --rm --pull=never -v "$PWD/tmp:/t" redis:7.4 rm -rf /t/heap-dumps`.
- Python 검사 스크립트는 노트북에서 돌려도 된다. 보고 증거로 쓸 때는 desktop worktree에서 한 번 더 돌린다.
**push 전에 검증하기.** push한 커밋은 고쳐 쓰지 않는다. 그래서 커밋 본문에 desktop 결과를 쓰거나 push가 허용되지 않았으면, 커밋 전에 바꾼 것을 패치로 보내 같은 트리에서 돌린다.
+10 -5
View File
@@ -74,6 +74,11 @@
| 생성 명령 | JPA adapter를 만들지 않음(서비스 전용 persistence leaf가 기본), 생성된 쓰기 API는 역할 매핑 전 403 | 위임 | `1101` 15절(r2-10) |
| `@SystemInvoked` | bean으로 등록돼 있으면 기동 실패, inbound adapter가 직접 부르지 못하게 ArchUnit | 위임 | `1103` 4절(RR-01-02) |
| 시스템 호출 경로 | 사용자가 닿는 전송(web·GraphQL·gRPC·WebSocket)만 `@SystemInvoked`에 닿지 못한다. 메시지 소비자·스케줄러는 `@SystemCaller(reason)` 표시로 허용 | 위임 | `1103` 9.1절(RR-01-12), 10절 r5-b |
| 배치 규칙 검사 | 저장소 루트와 `src/` 최상위 허용 목록을 `scripts/check-repo-layout.py`로 PR에서 막는다. 리뷰 기준에도 넣는다(매뉴얼 보강 작업) | 소유자(2026-11-07) | design-docs `repo-structure/README.md` 3.1절, `repo-structure/01-backend-layout.md` 10.3절 |
| `src/` 배치 | 들여온 플랫폼 넷(`messaging`, `grpc`, `grpc-advanced`, optional 빌드)을 `src/platforms/` 아래로 묶는다. registry `source_path`만 바꾸고 Gradle 경로는 그대로 둔다. `build-logic`·`gradle`·`config`는 Gradle 루트 표준이라 남기고, `composition`은 조립 계층이라 옮기지 않는다. `config/`에서 기능 하나가 주인인 데이터 파일은 그 leaf로 보낸다. Gradle 루트를 저장소 루트로 옮길지는 CI 재편 때 다시 본다 | 소유자(2026-11-07) | design-docs `repo-structure/README.md` 3.1절, `repo-structure/01-backend-layout.md` 6.1절 |
| 개발 compose 파일 | 저장소 루트에 `compose.yaml` 하나. 뒷단 서비스는 capability 이름 profile로 고르고, 마운트하는 보조 파일은 `compose/`에 둔다. 테스트 lane fixture는 그 lane을 가진 leaf로 보낸다(compose lane → app-bootstrap `compose-lanes/`, Redis topology → redis-sdk, NFS → fileserver). `docker-compose.dev.yml`은 `dev` 배포 프로필이 뜨는지 보는 lane fixture로 app-bootstrap에 둔다 | 소유자(2026-11-07) | design-docs `repo-structure/README.md` 3.1절, `repo-structure/01-backend-layout.md` 6.3절 |
| 인프라 실행 파일 | nginx 설정, Kubernetes PVC job, DB 역할 SQL은 이 repo에서 지우고, 기능이 운영 환경에 요구하는 조건만 그 기능 문서에 적는다. 아무도 쓰지 않는 `infra/` 파일도 지운다 | 소유자(2026-11-07) | design-docs `repo-structure/README.md` 3.1절, `repo-structure/01-backend-layout.md` 6.3절 |
| 샘플 모듈 | `src/sample-portfolio`와 `src/Dockerfile.sample`을 폴더째 지운다. 역할은 옮기지 않는다. 샘플 안에만 있던 템플릿 검사(OpenAPI 스냅숏, Date 헤더, 가상 스레드 MDC)도 함께 지운다. 예시는 매뉴얼과 생성 명령 출력이 맡는다 | 소유자(2026-11-07) | design-docs `repo-structure/README.md` 3.1절, `repo-structure/01-backend-layout.md` 6.2절 |
### 2.3 계약·오류
@@ -126,7 +131,7 @@
| --- | --- | --- | --- |
| JPA 기본값 | 트랜잭션 제한 30초, JDBC batch 50, H2 운영 jar 제거, 격리 수준 Hikari 고정, upsert `DO NOTHING` 후 갱신 | 위임 | `1101` 15절(04) |
| 포트 시그니처 | claim에 lease·`claimFence`, fileserver `claimDue`·`markAbandoned`·`claimToken` | 위임 | `1101` 15절 |
| 마이그레이션 번호 | 스트림별 순번. 샘플은 운영 스트림과 합쳐 도는 테스트가 있어 `V8_1`. notification은 `V13` | 위임 | `1101` 15절 |
| 마이그레이션 번호 | 스트림별 순번. ~~샘플은 운영 스트림과 합쳐 도는 테스트가 있어 `V8_1`.~~(샘플과 함께 사라짐, 2026-11-07) notification은 `V13` | 위임 | `1101` 15절 |
| V21 유일 인덱스 | 기존 중복이 있으면 마이그레이션 실패. runbook에 확인 쿼리 | 위임 | `1101` 15절 |
| 순서 번호 seed | counter가 없으면 전역 floor부터 | 위임 | `1103` 4절(RR-03-02) |
| 마이그레이션 잠금 | 강한 잠금을 거는 마이그레이션은 `SET LOCAL lock_timeout`, 같은 모양의 lane 테스트 | 위임 | `1103` 9.1절(RR-02-09) |
@@ -139,9 +144,9 @@
| 주제 | 결정 | 누가 | 출처 |
| --- | --- | --- | --- |
| 포스터 업로드 abort·reconcile 경합 | 먼저 끝난 쪽이 이김(이미 게시됐으면 abort는 409) | 소유자 | 결정 22 |
| work log 권한·batch | 관리자도 남의 work log 수정 불가, `batchCreate` 상한 1000·한 트랜잭션 | 위임 | `1101` 15절(09) |
| 이벤트 tenant·오류 코드 | 이벤트 tenant 범위 `global`, `WORKLOG_INVALID`·`OPERATION_NOT_FOUND` | 위임 | `1101` 15절(01) |
| 포스터 업로드 abort·reconcile 경합 | ~~먼저 끝난 쪽이 이김(이미 게시됐으면 abort는 409)~~ 샘플과 함께 사라짐(2026-11-07) | 소유자 | 결정 22 |
| work log 권한·batch | ~~관리자도 남의 work log 수정 불가, `batchCreate` 상한 1000·한 트랜잭션~~ 샘플과 함께 사라짐(2026-11-07) | 위임 | `1101` 15절(09) |
| 이벤트 tenant·오류 코드 | ~~이벤트 tenant 범위 `global`, `WORKLOG_INVALID`~~ 샘플과 함께 사라짐(2026-11-07). `OPERATION_NOT_FOUND`는 남는다 | 위임 | `1101` 15절(01) |
| outbox append 모델 | canonical(`OutboxAppendPort`)로 통일, legacy 포트·legacy Kafka 발행 경로 삭제 | 소유자 | 결정 7 |
| Kafka 소비 | 지원. `MessageHandler<T>` 하나 + starter-kafka가 consumer 조립 | 소유자 | 결정 10 |
| decode 타입 등록 | handler bean이 선언한 타입으로 decode 목록을 만든다 | 위임 | `1101` 15절(06-08 후속) |
@@ -149,7 +154,7 @@
| 끝나지 않는 재시도 | bridge가 원인 코드를 행에 남기고, 오래 재시도 중인 행 수·나이를 지표로, runbook에 park·재개 절차와 테스트된 SQL | 위임 | `1103` 4절(RR-05-03) |
| 카드 검증기 YAML | messaging leaf 테스트에서만 snakeyaml(main 금지) | 소유자 | 결정 29 |
| JWT audience·role | audience 필수, 자기 client role만(기존 배포는 env 하나를 채움) | 소유자 | `1101` 5절(02-03), 15절 |
| 데모 계정 | `local`·`test`·`demo` 프로필이 명시적으로 켜졌을 때만(허용 목록). 각 프로필은 sample이 실제로 뜨는 프로필 | 위임 | `1103` 4절(RR-07-02), 9.1절(RR2-04-02) |
| 데모 계정 | ~~`local`·`test`·`demo` 프로필이 명시적으로 켜졌을 때만(허용 목록). 각 프로필은 sample이 실제로 뜨는 프로필~~ 샘플과 함께 사라짐(2026-11-07) | 위임 | `1103` 4절(RR-07-02), 9.1절(RR2-04-02) |
| `fixture-` 값 거부 | 비밀로 분류된 키(`docs/registries/secrets-classification.yaml`)만 검사 | 위임 | `1103` 9.1절(RR2-04-01) |
| 파일 서버 인가 | 역할 검사(`file:*` 권한)와 소유자·tenant 검사(`ownerPrincipalId`)를 둘 다 | 소유자 | 결정 14, 결정 32 |
| cross-origin redirect | 호출자 헤더 전부 제거, 안전한 헤더만 유지 | 소유자 | 결정 23 |
+6 -6
View File
@@ -39,7 +39,7 @@
- **모양**: 조회 후 insert, 찾고 없으면 넣기, 트랜잭션 없는 `SKIP LOCKED`, lease 없는 claim, 프로세스 메모리에 둔 소유권.
- **막는 기준**: 유일성은 DB 유일 제약이 막고, adapter는 그 제약 위반만 기능 예외로 바꾼다. 여러 인스턴스가 집는 작업은 트랜잭션 안의 claim + lease로 소유권을 정한다.
- **볼 것**: 존재 확인 뒤 쓰기, 트랜잭션 밖 잠금, 메모리 안 소유권.
- **장치**: `CallerTransaction`(store는 호출자 트랜잭션을 요구), 동시 요청 통합 테스트(`CreatePosterConcurrencyIntegrationTest`). 정본: `docs/manual/04-persistence.md`.
- **장치**: `CallerTransaction`(store는 호출자 트랜잭션을 요구), 동시 요청 통합 테스트(실 DB lane에서 동시 요청 N개 → 행 1개). 정본: `docs/manual/04-persistence.md`.
### A6. 주장하는 것을 보지 않는 테스트
@@ -76,10 +76,10 @@
### A11. 샘플·fixture가 운영과 다르게 조립된다
- **모양**: 샘플이 자동 설정을 빼거나 런타임 기본값이 다르다. "따라 할 모양"으로 둔 fixture가 기동하지 않는다.
- **막는 기준**: 샘플은 운영과 같은 자동 설정과 런타임 기본값을 쓴다. 무엇을 빼면 이유와 대체 장치를 같은 곳에 적는다. 새 기능의 모양으로 둔 fixture는 실제로 기동되는 모양이어야 한다.
- **볼 것**: 샘플 `@SpringBootApplication(exclude=…)`, 샘플 `application.yml`과 기본 조합의 차이.
- **장치**: 샘플 전체 기동 lane(`:sample-portfolio:systemTest`, `mainCheck`), 샘플 실서버 계약(`sampleWebContractCheck`).
- **모양**: 따로 조립한 앱(fixture·데모)이 자동 설정을 빼거나 런타임 기본값이 다르다. "따라 할 모양"으로 둔 fixture가 기동하지 않는다.
- **막는 기준**: 따로 조립한 앱은 운영과 같은 자동 설정과 런타임 기본값을 쓴다. 무엇을 빼면 이유와 대체 장치를 같은 곳에 적는다. 새 기능의 모양으로 둔 fixture는 실제로 기동되는 모양이어야 한다.
- **볼 것**: 그 앱의 `@SpringBootApplication(exclude=…)`, 그 앱의 `application.yml`과 기본 조합의 차이.
- **장치**: 기본 조합 전체 기동 lane(app-bootstrap `systemTest`, PR `check`). 이 모양이 처음 나온 샘플 모듈은 2026-11-07에 지웠다.
### A12. 수정이 새 결함을 만든다
@@ -121,7 +121,7 @@
| 규칙을 일부러 다르게 둔 타입 | 그 타입의 Javadoc |
| 정적 분석 제외 | 제외 항목 옆 이유(`src/config/spotbugs/exclude-test.xml` 등) |
| 규칙의 예외 경로 | 이유를 요구하는 표시(`@SystemCaller(reason)`) |
| 복사본을 남긴 이유 | 가까운 `CLAUDE.md`(예: `src/messaging/CLAUDE.md`) |
| 복사본을 남긴 이유 | 가까운 `CLAUDE.md`(예: `src/platforms/messaging/CLAUDE.md`) |
| 되돌리기 비싼 선택 | `docs/adr/ADR-<영역>-<번호>-<제목>.md` |
## 패턴을 더하는 법
+13 -14
View File
@@ -20,11 +20,11 @@
| `qualityCheck` | SpotBugs, FindSecBugs(운영 코드) | PR(`ci` 안) | `src/build.gradle` |
| `testQualityCheck` | 같은 분석을 모든 테스트 source set에(`config/spotbugs/exclude-test.xml` 기준) | main(`mainCheck` 안), optional 빌드는 `ci` | `src/build.gradle` |
| `ci` | leaf `check`(API surface 포함) + `architectureCheck` + `qualityCheck` | PR | `ci-quality-gates.yml`: `./gradlew :ci :verifyDependencyLocks --warning-mode=fail` |
| `verifyStrictLaneStages --dry-run` | `explicitOnly`가 아닌 strict lane이 workflow가 실행하는 단계에 속하는가 | PR(두 빌드 각각) | `ci-quality-gates.yml`, optional 빌드는 `-p optional-platforms` |
| `:sample-portfolio:check :sample-portfolio:qualityCheck` | 샘플(`ci` 밖) | PR | `ci-quality-gates.yml` |
| `-p optional-platforms ci` | gRPC 플랫폼 빌드 | PR | `ci-quality-gates.yml` |
| `verifyStrictLaneStages --dry-run` | `explicitOnly`가 아닌 strict lane이 workflow가 실행하는 단계에 속하는가 | PR(두 빌드 각각) | `ci-quality-gates.yml`, optional 빌드는 `-p platforms/optional-build` |
| `-p platforms/optional-build ci` | gRPC 플랫폼 빌드 | PR | `ci-quality-gates.yml` |
| `bash scripts/verify-compose-profile-contracts.sh` | compose lane이 선언대로 렌더링되는가(저장소 루트에서) | PR | `ci-quality-gates.yml` |
| `mainCheck` | `configContractCheck` + `qualificationCheck`(`testQualityCheck` 포함) + 샘플 실서버 계약 + 샘플 전체 기동(`:sample-portfolio:systemTest`) + 공개 경로 스냅숏 + 전송·메시징 qualification lane + 생성 명령 왕복(`verifyFeatureScaffold`) + 모든 leaf의 `mainCheck`(document-contract lane 등) | main | `integration-main.yml`: `./gradlew :mainCheck --continue --warning-mode=fail` |
| `python3 scripts/check-repo-layout.py` | 저장소 루트와 `src/` 최상위에 허용 목록 밖의 항목이 없는가, registry 경로가 허용 폴더 안인가. 아무도 가리키지 않는 compose·스크립트 파일은 경고 | PR | `ci-quality-gates.yml` |
| `mainCheck` | `configContractCheck` + `qualificationCheck`(`testQualityCheck` 포함) + 공개 경로 스냅숏 + 전송·메시징 qualification lane + 생성 명령 왕복(`verifyFeatureScaffold`) + 모든 leaf의 `mainCheck`(document-contract lane 등) | main | `integration-main.yml`: `./gradlew :mainCheck --continue --warning-mode=fail` |
| `integrationCheck` | 선언된 strict integration lane 전체(실 컨테이너). 입력이 없는 lane은 빼고 이름을 댄다 | main·nightly | `integration-main.yml`, optional 빌드도 |
| `performanceCheck` | 선언된 performance lane 전체(부하·종료·풀·자원 한계, 실 서버와 컨테이너). 상한을 매번 단언한다. 손으로 돌리든 workflow든 같은 상한이다 | main·nightly | `integration-main.yml`, optional 빌드도. 5절 |
| `releaseCheck -PgitRevision=<sha>` | 릴리스 provenance + 공개 경로 스냅숏. sha 없이 돌리면 설계대로 실패한다 | 태그 | `release.yml` |
@@ -82,7 +82,7 @@ python3 scripts/check-work-docs.py --links $(git ls-files ':(glob)README.md' ':(
| brief의 말 | 돌릴 것 |
| --- | --- |
| pull request 단계 게이트 | (가)의 `# PR` 줄과 `verify-compose-profile-contracts.sh`, (나)에서 `pull_request`로 켜지는 것, (다) |
| pull request 단계 게이트 | (가)의 `# PR` 줄과 `verify-compose-profile-contracts.sh`·`check-repo-layout.py`, (나)에서 `pull_request`로 켜지는 것, (다) |
| main 단계 | (가)의 `# main push` 줄과 `run-compose-runtime-smoke.sh`, (나)에서 main `push`로 켜지는 것 |
| 라운드 끝 | 위 둘 전부와 (가)의 `# 태그` 두 줄 |
@@ -99,22 +99,22 @@ cd src
# PR: ci-quality-gates.yml
./gradlew :ci :verifyDependencyLocks --warning-mode=fail --no-build-cache --console=plain
./gradlew :verifyStrictLaneStages --dry-run --console=plain
./gradlew :sample-portfolio:check :sample-portfolio:qualityCheck --no-build-cache --console=plain
./gradlew -p optional-platforms ci --no-build-cache --console=plain
./gradlew -p optional-platforms :verifyStrictLaneStages --dry-run --console=plain
./gradlew -p platforms/optional-build ci --no-build-cache --console=plain
./gradlew -p platforms/optional-build :verifyStrictLaneStages --dry-run --console=plain
# main push: integration-main.yml
./gradlew :mainCheck --continue --warning-mode=fail --no-build-cache --console=plain
./gradlew :integrationCheck --continue --no-build-cache --console=plain
./gradlew :performanceCheck --continue --no-build-cache --console=plain
./gradlew -p optional-platforms performanceCheck --continue --no-build-cache --console=plain
./gradlew -p optional-platforms integrationCheck --no-build-cache --console=plain
./gradlew -p platforms/optional-build performanceCheck --continue --no-build-cache --console=plain
./gradlew -p platforms/optional-build integrationCheck --no-build-cache --console=plain
./gradlew :adapter:outbound:httpclient:test -Phttp3.tests.enabled=true --no-build-cache --console=plain # 실험 job, 실패해도 workflow는 통과
# 태그: release.yml (CI는 GITHUB_SHA로 커밋을 받는다. 손으로 돌릴 때는 -PgitRevision)
./gradlew :releaseCheck -PgitRevision="$(git rev-parse HEAD)" --no-build-cache --console=plain
./gradlew -p optional-platforms releaseCheck -PgitRevision="$(git rev-parse HEAD)" --no-build-cache --console=plain
./gradlew -p platforms/optional-build releaseCheck -PgitRevision="$(git rev-parse HEAD)" --no-build-cache --console=plain
cd ..
bash scripts/verify-compose-profile-contracts.sh
bash scripts/run-compose-runtime-smoke.sh --matrix src/config/runtime/compose-profile-contracts.json
python3 scripts/check-repo-layout.py
bash scripts/run-compose-runtime-smoke.sh --matrix src/app-bootstrap/compose-lanes/compose-profile-contracts.json
```
- 여러 명령으로 된 main job 둘은 그 job의 `run` 줄을 차례로 그대로 돌린다: `integration-main.yml`의 `configuration-cache`(로그에 "Reusing configuration cache."가 있어야 한다), `notification-platform.yml`의 `pr`(main push마다 경로와 상관없이 돈다).
@@ -184,9 +184,8 @@ for k in tests skipped failures errors; do cat $(find "$x" -name 'TEST-*.xml') |
| 장치 | 고정하는 것 | 단계 |
| --- | --- | --- |
| 요청당 SQL 수 단언(`WorkLogStatementCostSystemTest`) | 목록 20건과 100건의 문장 수가 같음, 제목만 바꾸는 PATCH가 컬렉션 행을 건드리지 않음, batch 생성이 JDBC batch로 감 | sample `systemTest`(`mainCheck`) |
| 자원 한계 lane | Tomcat·Jetty 부하·느린 클라이언트·종료, HTTP client 풀·스트리밍·재시도, Hikari 풀 | `performanceCheck` |
| JMH 벤치마크 | `src/messaging/messaging-kafka/src/jmh`, `src/messaging/messaging-testkit/src/jmh`, `src/adapter/outbound/httpclient/src/jmh` | 명시 실행 |
| JMH 벤치마크 | `src/platforms/messaging/messaging-kafka/src/jmh`, `src/platforms/messaging/messaging-testkit/src/jmh`, `src/adapter/outbound/httpclient/src/jmh` | 명시 실행 |
## 6. 게이트를 믿을 조건 — 거짓 통과 막기
+5 -5
View File
@@ -126,22 +126,22 @@
| 24 | 네이밍·의미 | `src/application-core/CLAUDE.md` 「Naming convention」, `NamingConventionTest` | 이름과 내용이 다름 |
| 25 | 조직 확장성 | 파생 서비스가 upstream을 받을 때 겹치는 곳 | 기능 패키지가 템플릿 패키지와 섞임 |
| 26 | Ownership | leaf마다 가까운 `CLAUDE.md`·README | 안내 문서 없음, 패키지가 평평해 소유가 안 보임 |
| 27 | 삭제 가능성 | capability `runtimeOnly` 한 줄 제거, sample 제거 | 한 줄 지워도 흔적이 남음, bootstrap이 capability 이름을 앎 |
| 27 | 삭제 가능성 | capability `runtimeOnly` 한 줄 제거 | 한 줄 지워도 흔적이 남음, bootstrap이 capability 이름을 앎 |
| 28 | 회복 가능성 | runbook SQL, DEAD·park, ledger 회수 | 영구히 막히는 key, 복구가 행마다 수작업 |
**따라갈 시나리오** (가이드 31절). 전체 리뷰는 시나리오마다 요청 하나를 끝까지 따라가며 입력 신뢰 수준, 권한 판단 위치, 규칙 소유자, 트랜잭션 시작과 끝, 외부 부작용, 오류 변환을 적는다. 해당 기능이 없으면 적용 제외 사유를 한 줄 적는다.
| 시나리오 | 따라갈 경로 |
| --- | --- |
| 정상 쓰기 요청 | sample `POST /api/worklogs`, 생성 명령으로 만든 기능 |
| 중복·동시 요청 | 같은 제목 동시 `POST /api/posters`, 멱등 키(`docs/manual/05-idempotency.md`) |
| 정상 쓰기 요청 | 생성 명령으로 만든 기능, durable operation `POST /operations` |
| 중복·동시 요청 | 같은 호출자가 같은 작업을 동시에 `POST /operations`(payload fingerprint로 하나만 받는다), 멱등 키(`docs/manual/05-idempotency.md`) |
| 외부 응답 지연·유실 | httpclient 시간 예산·breaker, 알림 발송 attempt |
| DB 오류·경쟁 | `PersistenceExceptionTranslator`, `@Version`, 트랜잭션 마감 |
| 메시지 중복·역순 | outbox relay, inbox 재전달, aggregate 순서 번호 |
| 신·구 버전 공존 | 마이그레이션 잠금, 배포 중 섞인 인스턴스 |
| 여러 서버의 작업 실행 | 알림 정산 job claim, gRPC ledger claim |
| 다른 사용자 리소스 접근 | 파일 서버 소유자 검사, sample 소유자 검사 |
| 큰 입력·목록 조회 | `GET /api/worklogs?size=100`, GraphQL 복잡도, JSON 아닌 본문 |
| 다른 사용자 리소스 접근 | 파일 서버 소유자 검사, durable operation 소유자·tenant 검사 |
| 큰 입력·목록 조회 | 파일 서버 업로드 크기 한도, GraphQL 복잡도, JSON 아닌 본문 |
| 종료·재시작 | relay·platform 종료 순서, 종료 시간 예산 |
| 선택 어댑터 제거 | `src/app-bootstrap/build.gradle`의 `runtimeOnly` 한 줄 제거 |
@@ -1,127 +0,0 @@
# Storage certification job.
#
# A PersistentVolumeClaim is not a filesystem contract. Whether an atomic rename, a same-file-store
# guarantee, or symlink refusal actually holds depends on the CSI driver, the StorageClass, the
# access mode, the backend, and the mount options — so this job records all five alongside the probe
# result. A certification without that tuple is not transferable to another cluster.
#
# The job writes a machine-readable result to the claim itself so the evidence lives with the volume
# it describes.
#
# kubectl apply -f infra/fileserver/kubernetes/pvc-certification-job.yaml
# kubectl logs job/fileserver-pvc-certification
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: fileserver-certification
labels:
app.kubernetes.io/name: fileserver
app.kubernetes.io/component: certification
spec:
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 1Gi
# Left unset on purpose: the certification is only meaningful for the class it actually ran on,
# so the operator names it explicitly rather than inheriting a cluster default.
storageClassName: ""
---
apiVersion: batch/v1
kind: Job
metadata:
name: fileserver-pvc-certification
labels:
app.kubernetes.io/name: fileserver
app.kubernetes.io/component: certification
spec:
backoffLimit: 0
template:
metadata:
labels:
app.kubernetes.io/name: fileserver
app.kubernetes.io/component: certification
spec:
restartPolicy: Never
securityContext:
runAsNonRoot: true
runAsUser: 10001
fsGroup: 10001
containers:
- name: certify
image: eclipse-temurin:21-jdk
env:
- name: FILESERVER_STORAGE_ROOT
value: /var/lib/backend/files
- name: KUBERNETES_VERSION
valueFrom:
fieldRef:
fieldPath: metadata.annotations['certification.fileserver/kubernetes-version']
- name: CSI_DRIVER
valueFrom:
fieldRef:
fieldPath: metadata.annotations['certification.fileserver/csi-driver']
- name: STORAGE_CLASS
valueFrom:
fieldRef:
fieldPath: metadata.annotations['certification.fileserver/storage-class']
- name: ACCESS_MODE
value: ReadWriteOnce
command:
- /bin/bash
- -c
- |
set -euo pipefail
ROOT="${FILESERVER_STORAGE_ROOT}"
mkdir -p "${ROOT}/staging" "${ROOT}/content"
# Atomic rename within one file store is the property the publish path depends on.
echo probe > "${ROOT}/staging/probe"
if mv "${ROOT}/staging/probe" "${ROOT}/content/probe" 2>/dev/null; then
ATOMIC_MOVE=true
else
ATOMIC_MOVE=false
fi
# Same device means a rename is a metadata operation rather than a copy.
STAGING_DEV=$(stat -c %d "${ROOT}/staging")
CONTENT_DEV=$(stat -c %d "${ROOT}/content")
[ "${STAGING_DEV}" = "${CONTENT_DEV}" ] && SAME_STORE=true || SAME_STORE=false
# O_EXCL create is what makes a publish create-only rather than an overwrite.
if (set -o noclobber; echo x > "${ROOT}/content/excl") 2>/dev/null; then
ATOMIC_CREATE=true
else
ATOMIC_CREATE=false
fi
cat > "${ROOT}/certification-result.json" <<RESULT
{
"kubernetesVersion": "${KUBERNETES_VERSION:-unknown}",
"csiDriver": "${CSI_DRIVER:-unknown}",
"storageClass": "${STORAGE_CLASS:-unknown}",
"accessMode": "${ACCESS_MODE}",
"backend": "$(stat -f -c %T "${ROOT}")",
"mountOptions": "$(findmnt -no OPTIONS --target "${ROOT}" || echo unknown)",
"atomicMove": ${ATOMIC_MOVE},
"sameFileStore": ${SAME_STORE},
"atomicCreate": ${ATOMIC_CREATE}
}
RESULT
cat "${ROOT}/certification-result.json"
# Fail closed: a volume that cannot publish atomically must not be certified silently.
[ "${SAME_STORE}" = "true" ] || { echo "staging and content are on different stores"; exit 1; }
volumeMounts:
- name: storage
mountPath: /var/lib/backend/files
securityContext:
allowPrivilegeEscalation: false
readOnlyRootFilesystem: true
capabilities:
drop: ["ALL"]
volumes:
- name: storage
persistentVolumeClaim:
claimName: fileserver-certification
-67
View File
@@ -1,67 +0,0 @@
# Fileserver front-proxy configuration.
#
# The application authorizes every download and then hands the transfer to Nginx with
# X-Accel-Redirect. Two properties make that safe, and both are enforced here rather than assumed:
#
# 1. /__files/ is `internal`, so it is reachable ONLY through an internal redirect the application
# issued. A direct request from a client returns 404 and never touches the content root.
# 2. The application never emits an absolute path. It emits a relative URI below /__files/, and
# the alias below is the only place that prefix becomes a filesystem location.
#
# Keep `alias` in sync with the storage root's content directory. A mismatch is a startup
# misconfiguration, not a runtime fallback: the application's startup validator checks that the
# internal mapping was proven before it accepts traffic.
worker_processes auto;
events {
worker_connections 4096;
}
http {
include mime.types;
default_type application/octet-stream;
sendfile on;
sendfile_max_chunk 2m;
tcp_nopush on;
keepalive_timeout 65;
# Uploads stream through to the application; buffering a large body to disk here would double
# the write and defeat the streaming upload path.
proxy_request_buffering off;
client_max_body_size 0;
server {
listen 8080;
# Public API. Everything, including download authorization, is decided by the application.
location / {
proxy_pass http://app:8081;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# The application must never see a client-supplied delegation header: it would let a
# caller name an arbitrary internal object.
proxy_set_header X-Accel-Redirect "";
}
# Internal transfer location. Not reachable from outside; see property (1) above.
location /__files/ {
internal;
alias /srv/files/content/;
sendfile on;
sendfile_max_chunk 2m;
# Uploaded content is never trusted to describe itself.
add_header X-Content-Type-Options nosniff always;
add_header Content-Disposition $upstream_http_content_disposition always;
add_header Cache-Control $upstream_http_cache_control always;
add_header ETag $upstream_http_etag always;
}
}
}
-12
View File
@@ -1,12 +0,0 @@
# HTTP Client Platform — local test topology
The suites drive these dependencies through Testcontainers and in-process fixtures, so nothing here
is required to run `./gradlew :adapter:outbound:httpclient:test`. These files exist for the nightly
lane and for reproducing a failure locally with the same images and ports CI uses.
| Directory | Purpose | Used by |
|---|---|---|
| `toxiproxy/` | TCP fault injection (latency, reset, bandwidth) | `httpClientFailureInjectionTest` |
| `tls/` | how the TLS and mTLS material is produced | TLS and mTLS suites |
| `proxy/` | forward proxy with CONNECT and proxy authentication | proxy contract suite |
| `oauth2/` | token endpoint behaviour under contention | OAuth2 suites |
-12
View File
@@ -1,12 +0,0 @@
# OAuth2 fixture
`OAuth2Fixture` exposes a token endpoint backed by the same deterministic fixture server as the rest
of the suite.
It counts token requests, which is what makes design §20.3's single-flight guarantee provable rather
than assumed: a hundred genuinely concurrent callers must produce exactly one token request. It can
also issue rotating token values, so a stale cached token is detectable, and queue a failure status
to exercise the refresh-failure path.
The token endpoint is configured as its own Named Client Profile, separate from the upstream it
issues tokens for.
-12
View File
@@ -1,12 +0,0 @@
# Forward proxy fixture
`ProxyFixture` runs an in-process forward proxy so the proxy lane needs no external service.
| Factory | Behaviour |
|---|---|
| `ProxyFixture.openProxy()` | accepts CONNECT and tunnels to the target |
| `ProxyFixture.authenticatingProxy(user, password)` | answers `407` until `Proxy-Authorization` matches |
The fixture records every request line and every `Proxy-Authorization` value it saw, which is what
lets the suite prove design §24.3: proxy credentials never appear on the target request, and a proxy
CONNECT failure is reported as `HttpProxyException` rather than as a target TLS failure.
-16
View File
@@ -1,16 +0,0 @@
# TLS fixtures
Certificates are generated **in process** by `TlsFixture`, not checked in. A committed private key
is a private key that leaks, and design §21.2 forbids key material in the repository.
`TlsFixture` produces, from a throwaway CA created per test run:
| Fixture | Purpose |
|---|---|
| `TlsFixture.trusted()` | a server certificate valid for the loopback host |
| `TlsFixture.hostnameMismatch()` | a certificate whose SAN does not match the connection host |
| `TlsFixture.expired()` | an already-expired certificate |
| `clientHandshake(true)` | client key material for the mTLS lane |
All three failure cases must classify as permanent (design §21.3) — never retried, never downgraded
to plaintext.
-17
View File
@@ -1,17 +0,0 @@
# Fault-injection topology for the HTTP Client Platform failure suite (design §28.1, §28.3).
#
# The suite normally drives Toxiproxy through Testcontainers. This compose file exists for the
# nightly lane and for reproducing a failure locally with the exact same image and ports.
services:
toxiproxy:
image: ghcr.io/shopify/toxiproxy:2.9.0
container_name: httpclient-toxiproxy
ports:
- "8474:8474" # control API
- "18080:18080" # proxied upstream: plaintext
- "18443:18443" # proxied upstream: TLS
healthcheck:
test: ["CMD", "/toxiproxy-cli", "list"]
interval: 5s
timeout: 3s
retries: 10
-39
View File
@@ -1,39 +0,0 @@
# infra/jpa/postgres
Server-side settings the JPA platform's contracts assume, and why each one matters.
The contract suites start their own containers through
`dev.caskeleton.adapter.outbound.persistence.testkit.postgresql.PostgreSqlContainerFactory`, so
nothing here is needed to run them. This directory records what a *deployed* PostgreSQL has to look
like for the platform's guarantees to hold, because several of them are server settings rather than
application code.
## Settings the platform depends on
| Setting | Why the platform cares |
|---|---|
| `statement_timeout` | The last bound on a runaway statement. The platform sets transaction timeouts, but a single statement inside a transaction can still outlive the request that asked for it. |
| `idle_in_transaction_session_timeout` | An idle open transaction holds its locks and its snapshot indefinitely, which blocks writers and prevents vacuum. This is what turns "someone left a transaction open" into a bounded incident. |
| `lock_timeout` | A cluster-wide floor under the per-request lock bounds in `PostgreSqlLockOptions`. |
| `max_connections` | The number `app.jpa-platform.datasource.maximum-pool-size` must be sized against — across every instance, and allowing for `REQUIRES_NEW` taking a second connection while pinning the first. |
| `default_transaction_isolation` | Left at `read committed`. The platform selects `repeatable read` or `serializable` per transaction profile; changing the default would silently change every transaction that did not ask. |
## Suggested baseline
```conf
statement_timeout = '30s'
idle_in_transaction_session_timeout = '60s'
lock_timeout = '10s'
default_transaction_isolation = 'read committed'
```
These are starting points, not recommendations: the right `statement_timeout` depends on the
slowest legitimate query in the application, and setting it below that turns a working report into
an error. Measure before pinning.
## What is deliberately not configured here
- **Roles.** Credential separation lives in [`../roles/runtime-roles.sql`](../roles/runtime-roles.sql).
- **Schema.** Flyway owns it (design §31). Nothing in this directory creates a table.
- **Extensions.** The platform's PostgreSQL support — JSONB, arrays, ranges, `SKIP LOCKED`,
`ON CONFLICT` — is all core PostgreSQL. No extension is required, and none should be assumed.
-54
View File
@@ -1,54 +0,0 @@
-- Runtime / migration / admin credential separation for the JPA persistence platform.
-- Design §36; enforced at startup by PostgreSqlRuntimeRoleVerifier + DatabaseRolePolicy.
--
-- The separation is what makes "Flyway owns schema change" enforceable rather than aspirational.
-- If the application's own credential cannot execute DDL, then no code path, no library, and no
-- injected statement can alter the schema at runtime — regardless of what the application intended.
--
-- Run as a superuser once per database. Replace the placeholder passwords with values from the
-- deployment's secret store; they are intentionally not committed.
-- 1. The schema the application owns. Owned by the migration role, not the runtime role.
create schema if not exists app authorization app_migration;
-- 2. Roles.
-- app_migration : owns the schema, applies Flyway migrations. DDL.
-- app_runtime : the application's credential. DML only, no DDL, no CREATE.
-- app_admin : J4 operations — COPY, backfill, maintenance. Never used by request paths.
create role app_migration login password 'REPLACE_FROM_SECRET_STORE';
create role app_runtime login password 'REPLACE_FROM_SECRET_STORE';
create role app_admin login password 'REPLACE_FROM_SECRET_STORE';
-- 3. Revoke the PUBLIC grants that make the checks in DatabaseRolePolicy necessary.
-- Before PostgreSQL 15, PUBLIC held CREATE on the public schema — which is how an unprivileged
-- role ends up able to plant an object that shadows a real one through search_path.
revoke all on database current_database() from public;
revoke create on schema public from public;
-- 4. Runtime: read and write rows in the application schema. Nothing else.
grant connect on database current_database() to app_runtime;
grant usage on schema app to app_runtime;
grant select, insert, update, delete on all tables in schema app to app_runtime;
grant usage, select on all sequences in schema app to app_runtime;
-- Tables created by future migrations must inherit the same grants, or the first deployment after
-- a new table silently fails at runtime with a permission error.
alter default privileges for role app_migration in schema app
grant select, insert, update, delete on tables to app_runtime;
alter default privileges for role app_migration in schema app
grant usage, select on sequences to app_runtime;
-- 5. Explicitly deny the two privileges the startup verifier checks for.
revoke create on schema app from app_runtime;
revoke create on database current_database() from app_runtime;
-- 6. Admin: bulk operations under an audited identity, still without schema ownership.
grant connect on database current_database() to app_admin;
grant usage on schema app to app_admin;
grant select, insert, update, delete on all tables in schema app to app_admin;
alter default privileges for role app_migration in schema app
grant select, insert, update, delete on tables to app_admin;
-- 7. Pin the runtime search_path so an unqualified name cannot resolve anywhere unexpected.
alter role app_runtime set search_path = app, pg_catalog;
alter role app_admin set search_path = app, pg_catalog;
-43
View File
@@ -1,43 +0,0 @@
# Commit-ambiguity failure injection for the JPA platform (design §39).
#
# The suite needs a proxy rather than a kill switch because the scenario that matters cannot be
# produced any other way. Stopping the container, killing the process, or closing the client socket
# all break *before* the server commits — the easy case, where the transaction rolled back and the
# use case may simply be re-run. The hard case is a commit the server completed whose
# acknowledgement never came back, and it only exists if you can cut the return path while leaving
# the forward path intact.
#
# That is what CommitAmbiguityProxy does with a downstream-only toxic, and it is the one scenario
# that distinguishes a platform that reports completion-unknown from one that retries a write which
# already succeeded.
#
# Ordinary contract runs use Testcontainers and do not need this file; it exists for reproducing a
# failure scenario by hand.
services:
postgres:
image: postgres:16-alpine
environment:
POSTGRES_DB: jpa_failure
POSTGRES_USER: jpa_failure
POSTGRES_PASSWORD: jpa_failure
# No published port: the suite must reach PostgreSQL only through the proxy, or the injected
# fault can be bypassed by connecting directly and the test passes without testing anything.
expose:
- "5432"
healthcheck:
test: ["CMD-SHELL", "pg_isready -U jpa_failure -d jpa_failure"]
interval: 2s
timeout: 3s
retries: 30
toxiproxy:
image: ghcr.io/shopify/toxiproxy:2.11.0
depends_on:
postgres:
condition: service_healthy
ports:
# 8474 is the control API the suite drives; 8666 is the proxied PostgreSQL port.
- "8474:8474"
- "8666:8666"
command: ["-host", "0.0.0.0"]
-33
View File
@@ -1,33 +0,0 @@
# Kafka 4.3.x in KRaft mode.
#
# Single broker on purpose: this compose file exists to reproduce the platform's Stable profile
# locally, not to model a production cluster. The settings below are the ones the profile guard
# enforces, so a local run fails the same way a misconfigured deployment would.
services:
kafka:
image: apache/kafka:4.3.0
container_name: messaging-kafka
ports:
- "9092:9092"
environment:
KAFKA_NODE_ID: 1
KAFKA_PROCESS_ROLES: broker,controller
KAFKA_LISTENERS: PLAINTEXT://:9092,CONTROLLER://:9093
KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://localhost:9092
KAFKA_CONTROLLER_LISTENER_NAMES: CONTROLLER
KAFKA_CONTROLLER_QUORUM_VOTERS: 1@localhost:9093
KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT
# acks=all is only a durability guarantee when more than one replica must acknowledge.
# With a single broker the platform still requires acks=all; min.insync.replicas is 1 here
# and is expected to be 2 in any environment that claims replication evidence.
KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: 1
KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: 1
KAFKA_MIN_INSYNC_REPLICAS: 1
# Topology is created by infrastructure, never by the application.
KAFKA_AUTO_CREATE_TOPICS_ENABLE: "false"
healthcheck:
test: ["CMD-SHELL", "/opt/kafka/bin/kafka-broker-api-versions.sh --bootstrap-server localhost:9092 >/dev/null 2>&1"]
interval: 5s
timeout: 10s
retries: 20
@@ -1,27 +0,0 @@
# PostgreSQL 16 for the Outbox and Inbox.
#
# logical replication stays enabled so a CDC relay can be tried against the same database the polling
# relay uses. The repository ships no CDC relay (the Debezium mapping was removed on 2026-09-25).
services:
postgres:
image: postgres:16-alpine
container_name: messaging-postgres
ports:
- "5432:5432"
environment:
POSTGRES_DB: messaging
POSTGRES_USER: messaging
POSTGRES_PASSWORD: messaging
command:
- "postgres"
- "-c"
- "wal_level=logical"
- "-c"
- "max_replication_slots=4"
- "-c"
- "max_wal_senders=4"
healthcheck:
test: ["CMD-SHELL", "pg_isready -U messaging -d messaging"]
interval: 5s
timeout: 5s
retries: 20
-35
View File
@@ -1,35 +0,0 @@
# TLS material
Production profiles require TLS **and** hostname verification; `MessageSecurityValidator` fails
startup without either.
No key material is committed here, and none should be. Certificates are issued by the deployment's
own PKI and mounted at runtime; a keystore in a repository is a credential in a repository, and
rotating it means a commit.
## Local development
The compose files in the sibling directories run plaintext listeners deliberately. They exist to
reproduce the *messaging* semantics locally, not the transport security, and running them with
`production: false` in the destination profile is what keeps the validator honest — a profile marked
`production: true` against a plaintext broker must fail, and that is a test, not an inconvenience.
## Generating a local CA for TLS testing
```bash
openssl req -x509 -newkey rsa:4096 -sha256 -days 30 -nodes \
-keyout ca.key -out ca.crt -subj "/CN=messaging-local-ca"
openssl req -newkey rsa:4096 -nodes -keyout broker.key -out broker.csr \
-subj "/CN=localhost"
openssl x509 -req -in broker.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
-out broker.crt -days 30 -sha256 \
-extfile <(printf "subjectAltName=DNS:localhost,IP:127.0.0.1")
```
The `subjectAltName` is not optional. Hostname verification is required in production profiles, and
a certificate without a SAN fails it — which is the correct outcome, not something to work around by
disabling the check.
Generated files are ignored by `.gitignore` in this directory.
@@ -1,18 +0,0 @@
# Toxiproxy, for the failures that matter most.
#
# The platform's hardest guarantee is that a lost confirmation is reported as AMBIGUOUS rather than
# guessed. A healthy broker will not lose one on request, so the chaos suite puts a proxy in front of
# it and severs the connection after the record was accepted but before the acknowledgement arrives.
services:
toxiproxy:
image: ghcr.io/shopify/toxiproxy:2.12.0
container_name: messaging-toxiproxy
ports:
- "8474:8474" # control API
- "19092:19092" # proxied Kafka
- "15433:15433" # proxied PostgreSQL
healthcheck:
test: ["CMD", "/toxiproxy-cli", "list"]
interval: 5s
timeout: 5s
retries: 20
@@ -1,94 +0,0 @@
# Toxiproxy fault injection for the notification delivery platform.
#
# Scope, stated up front: this is the *nightly and release* fault suite, not the PR gate. The PR
# suite runs against a loopback socket harness in-process — deterministic, no Docker, no provider
# sandbox — because a gate that needs infrastructure is a gate people learn to skip. What lives
# here are the faults that harness cannot produce: real TCP behaviour under latency, bandwidth
# starvation, and connection resets at a point the JVM's own socket layer decides.
#
# Usage:
# docker compose -f infra/notification/toxiproxy/docker-compose.yml up -d
# ./gradlew :adapter:outbound:notification:test -Dnotification.faultProxy=http://127.0.0.1:8474
#
# The proxies below front *stub* upstreams, never a provider's real API. Pointing a toxic proxy at
# a live provider sends real notifications to real people from a test run, and adds a rate-limit
# incident on an account the team shares.
services:
toxiproxy:
image: ghcr.io/shopify/toxiproxy:2.11.0
container_name: notification-toxiproxy
ports:
- "8474:8474" # control API
- "18081:18081" # -> ses-stub
- "18082:18082" # -> twilio-stub
- "18083:18083" # -> push-stub (APNs / FCM / Web Push)
networks: [notification-fault]
healthcheck:
test: ["CMD", "/toxiproxy-cli", "list"]
interval: 5s
timeout: 3s
retries: 10
# Deterministic upstreams. Each returns the provider's success shape and nothing else; the
# interesting behaviour is injected by the proxy in front of it, not by the stub.
ses-stub:
image: mendhak/http-https-echo:35
environment:
HTTP_PORT: "8080"
networks: [notification-fault]
twilio-stub:
image: mendhak/http-https-echo:35
environment:
HTTP_PORT: "8080"
networks: [notification-fault]
push-stub:
image: mendhak/http-https-echo:35
environment:
HTTP_PORT: "8080"
networks: [notification-fault]
# Creates the proxies and the toxics once the control API is up. Kept as a job rather than a
# README step so the topology is reproducible and reviewable rather than typed from memory.
provision:
image: ghcr.io/shopify/toxiproxy:2.11.0
depends_on:
toxiproxy:
condition: service_healthy
networks: [notification-fault]
entrypoint:
- /bin/sh
- -c
- |
set -e
CLI="/toxiproxy-cli -h toxiproxy:8474"
$$CLI create -l 0.0.0.0:18081 -u ses-stub:8080 ses
$$CLI create -l 0.0.0.0:18082 -u twilio-stub:8080 twilio
$$CLI create -l 0.0.0.0:18083 -u push-stub:8080 push
# Response loss after the request was committed: the provider received and acted on the
# message, and the answer never came back. This is the AMBIGUOUS case, and it is the one
# fault no provider's documentation describes.
$$CLI toxic add -t timeout -a timeout=0 -n response_loss --downstream --toxicity 0 ses
$$CLI toxic add -t timeout -a timeout=0 -n response_loss --downstream --toxicity 0 twilio
$$CLI toxic add -t timeout -a timeout=0 -n response_loss --downstream --toxicity 0 push
# Latency past the adapter's own timeout, to prove the timeout is the adapter's decision
# rather than the socket's.
$$CLI toxic add -t latency -a latency=8000 -n slow --toxicity 0 ses
$$CLI toxic add -t latency -a latency=8000 -n slow --toxicity 0 twilio
$$CLI toxic add -t latency -a latency=8000 -n slow --toxicity 0 push
# Partial write: the connection dies mid-body. Distinct from response loss, because the
# provider never got a complete request and the attempt is genuinely retryable.
$$CLI toxic add -t limit_data -a bytes=64 -n partial_write --upstream --toxicity 0 ses
$$CLI toxic add -t limit_data -a bytes=64 -n partial_write --upstream --toxicity 0 twilio
$$CLI toxic add -t limit_data -a bytes=64 -n partial_write --upstream --toxicity 0 push
echo "proxies ready; toxics are registered at toxicity=0 and enabled per test"
$$CLI list
networks:
notification-fault:
driver: bridge
+14 -12
View File
@@ -1,31 +1,33 @@
#!/usr/bin/env bash
# The ordered local start-up: compile, Docker preflight, dependency wait, migrate-and-start, smoke.
#
# scripts/bootstrap-local.sh # the `local` overlay (docker-compose.local.yml)
# scripts/bootstrap-local.sh <profile> # docker-compose.<profile>.yml merged onto docker-compose.yml
# scripts/bootstrap-local.sh
#
# It runs the development stack, compose.yaml at the repository root: the application container in
# the `local` runtime and the PostgreSQL service of the `jpa` profile. Naming a service on the
# command line switches its profile on, so no --profile is needed here.
#
# This was the build-logic `ca.developer-bootstrap` plugin (`./gradlew bootstrap`). Starting
# containers and probing an HTTP endpoint is not a build rule, so it is a script now (review
# 2026-09-24 BUILD-O3-5). The four stages and their order are unchanged: the next stage starts only
# when the previous one succeeded, and the app stage waits for startup Flyway through the compose
# healthcheck before the smoke probe runs.
#
# Until 2026-11-07 it merged docker-compose.yml with docker-compose.local.yml and asked for a `db`
# service neither file had defined since the database moved to a third file, so the documented
# first run stopped at stage 2.
set -euo pipefail
readonly repository_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
readonly profile="${1:-local}"
readonly base_compose="${repository_dir}/docker-compose.yml"
readonly overlay="${repository_dir}/docker-compose.${profile}.yml"
readonly health_endpoint="${BOOTSTRAP_HEALTH_ENDPOINT:-http://localhost:8080/api/healthcheck}"
readonly smoke_timeout_seconds="${BOOTSTRAP_SMOKE_TIMEOUT_SECONDS:-60}"
if [[ ! -f "${overlay}" ]]; then
available="$(cd "${repository_dir}" && ls docker-compose.*.yml 2>/dev/null \
| sed -e 's/^docker-compose\.//' -e 's/\.yml$//' | tr '\n' ' ')"
echo "bootstrap: '${profile}' names no overlay; expected $(basename "${overlay}") beside" \
"docker-compose.yml. Available: ${available:-none}" >&2
if [[ $# -gt 0 ]]; then
echo "bootstrap: takes no arguments; the stack is compose.yaml. Backing services by profile:" \
"docker compose --profile <profile> up -d --wait (see the head of compose.yaml)" >&2
exit 64
fi
compose=(docker compose -f "${base_compose}" -f "${overlay}")
compose=(docker compose -f "${repository_dir}/compose.yaml")
echo "bootstrap 1/4: compiling the default application composition"
(cd "${repository_dir}/src" && ./gradlew :app-bootstrap:compileTestJava --console=plain)
@@ -35,7 +37,7 @@ if ! docker info >/dev/null 2>&1; then
exit 69
fi
echo "bootstrap 2/4: starting the ${profile} PostgreSQL dependency and waiting for readiness"
echo "bootstrap 2/4: starting the PostgreSQL dependency and waiting for readiness"
"${compose[@]}" up -d --wait db
echo "bootstrap 3/4: building and starting the app; startup Flyway finishes before health is ready"
+210
View File
@@ -0,0 +1,210 @@
#!/usr/bin/env python3
"""저장소 루트와 src/ 최상위에 허용 목록 밖의 항목이 생기면 실패한다.
왜: src/ 아래 계층이 아닌 폴더가 2026-07-24의 둘에서 두 달 사이 여덟으로 늘었고, 어느 커밋도 최상위
모양을 묻지 않았다. 루트에는 개발 환경·테스트 fixture·운영 인프라가 섞인 compose 파일과 infra/ 폴더가
쌓였다(2026-11-07 저장소 정리, design-docs repo-structure/01-backend-layout.md). 소유자는 배치 규칙을
리뷰 기준에 두고, 이 허용 목록 검사로도 막기로 정했다(같은 날, repo-structure/README.md 3.1절).
무엇을 보나:
1. 저장소 루트의 추적 파일·폴더가 ROOT_ALLOWED 안에 있는가.
2. src/ 바로 아래의 추적 파일·폴더가 SRC_ALLOWED 안에 있는가.
3. registry(src/config/architecture/modules.json)의 모든 source_path가 허용된 src/ 폴더 아래에 있는가.
4. (경고만) 개발 환경·테스트 fixture 파일(compose 파일, 셸 스크립트, compose/ 아래 보조 파일)을 다른
추적 파일이 하나도 가리키지 않으면 이름을 출력한다. 아무도 읽지 않는 파일이 소리 없이 남는 것이
infra/ 12개가 쌓인 방식이다. 경로를 변수로 조립하는 workflow는 이 검사가 따라가지 못하므로 경고로만 둔다.
추적 파일만 본다(git ls-files). build 출력과 IDE 폴더는 처음부터 대상이 아니다.
새 최상위 항목이 정말 필요하면 아래 목록과 루트 CLAUDE.md 5절 「최상위 폴더는 정해진 것만 둔다」를 같은
변경에서 고친다. 최상위 폴더를 만들거나 옮기는 일은 파일 하나여도 큰 일이다(docs/work/README.md 2절).
Gradle 밖에 둔다: 빌드는 저장소 배치를 판단하지 않는다(scripts/check-work-docs.py와 같은 자리).
python3 scripts/check-repo-layout.py
"""
from __future__ import annotations
import json
import subprocess
import sys
from pathlib import Path, PurePosixPath
REPO_ROOT = Path(__file__).resolve().parent.parent
REGISTRY = "src/config/architecture/modules.json"
# 저장소 루트: 문서·스크립트·CI·개발 환경과 Gradle 루트(src)뿐이다.
ROOT_ALLOWED = {
# 폴더
".claude": "에이전트 세션 설정(추적되는 settings.json)",
".github": "workflow와 공용 action",
"compose": "compose.yaml이 마운트하는 보조 파일",
"docs": "문서",
"scripts": "Gradle 밖 검사·실행 스크립트",
"src": "Gradle 루트",
# 파일
".gitattributes": "Git 설정",
".gitignore": "Git 설정",
".tool-versions": "JDK 버전 고정",
".trivyignore.yaml": "취약점 검사 예외",
"AGENTS.md": "규칙 정본",
"CLAUDE.md": "작업 지도",
"README.md": "저장소 소개",
"compose.yaml": "개발 환경(하나뿐)",
"renovate.json": "의존성 갱신 봇 설정",
"skills-lock.json": "에이전트 스킬 고정",
"testcontainers.properties.example": "Testcontainers 로컬 설정 예",
}
# src/ 바로 아래: 계층·조립 leaf, 들여온 제품 묶음, Gradle 루트 표준 폴더와 빌드 파일.
SRC_ALLOWED = {
# 계층과 조립
"domain-core": "계층",
"shared-contract": "계층",
"application-core": "계층",
"application-fileserver": "계층(capability)",
"application-notification": "계층(capability)",
"application-objectstorage": "계층(capability)",
"adapter": "계층(adapter leaf 묶음)",
"composition": "조립(Clean Architecture의 Main)",
"app-bootstrap": "조립 루트",
# 들여온 제품
"platforms": "들여온 제품(messaging, grpc, grpc-advanced)과 optional 빌드",
# Gradle 루트 표준
"build-logic": "빌드 규칙(included build)",
"config": "빌드 전체 도구 설정(registry, checkstyle, spotbugs, 테스트 이미지)",
"gradle": "wrapper와 버전 카탈로그",
# 파일
".dockerignore": "이미지 빌드 context",
".env.example": "env 계약",
".env.local.example": "로컬 env 예",
".gitignore": "Git 설정",
"Dockerfile": "릴리스 이미지",
"README.md": "빌드·env 안내",
"build.gradle": "루트 빌드",
"gradle.properties": "Gradle 설정",
"gradlew": "wrapper",
"gradlew.bat": "wrapper",
"settings-gradle.lockfile": "settings 잠금",
"settings.gradle": "settings",
}
# 아무도 가리키지 않으면 경고할 파일: 개발 환경과 테스트 fixture.
FIXTURE_SUFFIXES = (".sh", ".acl", ".json", ".yaml", ".yml")
FIXTURE_PREFIXES = ("compose/", "scripts/", "src/app-bootstrap/compose-lanes/")
HISTORY_PREFIXES = (
"docs/reviews/",
"docs/superpowers/",
"docs/evidence/",
"docs/study/",
"docs/adr/",
)
def tracked_files() -> list[str]:
result = subprocess.run(
["git", "ls-files", "-z"],
cwd=REPO_ROOT,
check=True,
capture_output=True,
)
return [path for path in result.stdout.decode("utf-8").split("\0") if path]
def top_level(paths: list[str], prefix: str) -> set[str]:
names = set()
for path in paths:
if not path.startswith(prefix):
continue
rest = path[len(prefix):]
names.add(rest.split("/", 1)[0])
return names
def registry_violations() -> list[str]:
modules = json.loads((REPO_ROOT / REGISTRY).read_text(encoding="utf-8"))["modules"]
problems = []
for module in modules:
source = PurePosixPath(module["source_path"])
parts = source.parts
if len(parts) < 2 or parts[0] != "src" or parts[1] not in SRC_ALLOWED:
problems.append(
f"{REGISTRY}: {module['id']} source_path {source} is not under an allowed src/ folder"
)
return problems
def is_fixture(path: str) -> bool:
if path.endswith(("README.md", ".gitignore")):
return False
name = PurePosixPath(path).name
if path.startswith(FIXTURE_PREFIXES) and name.endswith(FIXTURE_SUFFIXES):
return True
return "compose" in name and name.endswith((".yaml", ".yml"))
def unreferenced_fixtures(paths: list[str]) -> list[str]:
this_script = str(Path(__file__).resolve().relative_to(REPO_ROOT))
readable = [
p for p in paths if not p.startswith(HISTORY_PREFIXES) and p != this_script
]
texts = {}
for path in readable:
file = REPO_ROOT / path
try:
if file.stat().st_size > 2_000_000:
continue
texts[path] = file.read_text(encoding="utf-8")
except (UnicodeDecodeError, OSError):
continue
lonely = []
for path in sorted(p for p in paths if is_fixture(p)):
pure = PurePosixPath(path)
# The file's own path or name, or its folder when a compose file mounts the whole folder
# (./compose/redis/acl). A one-segment folder such as compose/ names too much to count.
needles = {path, pure.name}
if len(pure.parent.parts) >= 2:
needles.add(str(pure.parent))
referenced = any(
other != path and any(needle in text for needle in needles)
for other, text in texts.items()
)
if not referenced:
lonely.append(path)
return lonely
def main() -> int:
paths = tracked_files()
failures = []
for name in sorted(top_level(paths, "") - ROOT_ALLOWED.keys()):
failures.append(f"repository root: '{name}' is not in ROOT_ALLOWED")
for name in sorted(top_level(paths, "src/") - SRC_ALLOWED.keys()):
failures.append(f"src/: '{name}' is not in SRC_ALLOWED")
failures.extend(registry_violations())
for path in unreferenced_fixtures(paths):
print(f"warning: no tracked file refers to {path}")
if failures:
for failure in failures:
print(f"FAIL: {failure}", file=sys.stderr)
print(
"check-repo-layout: a new top-level entry changes the repository's shape. If it is "
"wanted, add it to the allow list in scripts/check-repo-layout.py and to CLAUDE.md "
"section 5 in the same change.",
file=sys.stderr,
)
return 1
print(
f"check-repo-layout: OK — {len(top_level(paths, ''))} root entries, "
f"{len(top_level(paths, 'src/'))} src/ entries, registry paths inside allowed folders"
)
return 0
if __name__ == "__main__":
sys.exit(main())
@@ -8,7 +8,7 @@ import java.util.UUID;
* Mints {@link __Feature__Id}s as random (version 4) UUIDs from the JDK's secure generator.
*
* <p>Random UUIDs scatter inserts across a B-tree primary key. When __Feature__ rows are written
* often, switch to a time-ordered UUIDv7 as the sample's {@code UuidWorkLogIdFactory} does; the
* often, switch to a time-ordered UUIDv7 as {@code UuidV7DurableOperationIdFactory} does; the
* domain contract (canonical UUID text) does not change.
*/
public final class Uuid__Feature__IdFactory implements __Feature__IdFactory {
+71 -19
View File
@@ -13,6 +13,8 @@
# compared with the lane's expectedCapabilitiesOn and expectedPersistenceVendor;
# 4. every one-shot the lane declares, each of which must exit zero — a missing or skipped
# required client is a lane failure, not a lane that had nothing to check;
# 4a. no container of the lane restarted or was killed for memory — a container that died and came
# back between the checks above would otherwise leave every one of them green;
# 5. sanitized evidence;
# 6. teardown scoped to this project alone, on success and failure alike, after the logs are
# collected rather than before.
@@ -22,7 +24,7 @@
set -euo pipefail
REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
CONTRACTS="${REPO_ROOT}/src/config/runtime/compose-profile-contracts.json"
CONTRACTS="${REPO_ROOT}/src/app-bootstrap/compose-lanes/compose-profile-contracts.json"
EVIDENCE_ROOT="${REPO_ROOT}/src/app-bootstrap/build/evidence/runtime-smoke"
RUN_ID="$(date -u +%Y%m%dT%H%M%SZ)-$$"
# Compose project names accept lowercase alphanumerics, hyphens and underscores only, so the run id
@@ -32,7 +34,7 @@ PROJECT_RUN_ID="$(tr '[:upper:]' '[:lower:]' <<<"${RUN_ID}")"
# The lanes boot the qualification image: the application with every capability module on the
# classpath (src/Dockerfile COMPOSITION, app-bootstrap qualificationBootJar). The default image is
# the composition a service ships and carries none of them, so a lane that switches JPA or Kafka on
# would have nothing to switch. docker-compose.yml passes this to the build and puts it in the tag.
# would have nothing to switch. compose.yaml passes this to the build and puts it in the tag.
export COMPOSITION=qualification
# Every capability is on while its module is present, so each lane starts from all of them off and
@@ -79,6 +81,9 @@ for tool in jq docker; do
done
[[ -r "${CONTRACTS}" ]] || { echo "missing ${CONTRACTS}" >&2; exit 78; }
# The lane-only TLS overlay's keypair directory (src/app-bootstrap/compose-lanes/tls.yaml).
LANE_POSTGRES_TLS="${REPO_ROOT}/src/app-bootstrap/compose-lanes/postgres/tls"
# ---- per-lane state, cleaned up by the trap ---------------------------------
PROJECT=""
LANE_TMP=""
@@ -109,14 +114,14 @@ cleanup_lane() {
fi
[[ -n "${LANE_TMP}" && -d "${LANE_TMP}" ]] && rm -rf "${LANE_TMP}"
# .env.lane is gone — the lane's values live in the generated overlay now — but a file left by an
# older revision of this script would still be read by the local overlay's env_file list.
rm -f "${REPO_ROOT}/src/.env.lane" "${REPO_ROOT}/infra/keycloak/secrets/graphql-smoke-client-secret"
# older revision of this script would still be read by an env_file list of an older stack.
rm -f "${REPO_ROOT}/src/.env.lane" "${REPO_ROOT}/compose/keycloak/secrets/graphql-smoke-client-secret"
# The lane keypair, including the CA's private half. A certificate that outlives the run it was
# made for is a credential nobody is tracking.
rm -f "${REPO_ROOT}"/infra/postgres/tls/ca.key "${REPO_ROOT}"/infra/postgres/tls/ca.crt \
"${REPO_ROOT}"/infra/postgres/tls/ca.srl "${REPO_ROOT}"/infra/postgres/tls/server.key \
"${REPO_ROOT}"/infra/postgres/tls/server.crt "${REPO_ROOT}"/infra/postgres/tls/server.csr \
"${REPO_ROOT}"/infra/mailpit/tls/server.key "${REPO_ROOT}"/infra/mailpit/tls/server.crt
rm -f "${LANE_POSTGRES_TLS}"/ca.key "${LANE_POSTGRES_TLS}"/ca.crt \
"${LANE_POSTGRES_TLS}"/ca.srl "${LANE_POSTGRES_TLS}"/server.key \
"${LANE_POSTGRES_TLS}"/server.crt "${LANE_POSTGRES_TLS}"/server.csr \
"${REPO_ROOT}"/compose/mailpit/tls/server.key "${REPO_ROOT}"/compose/mailpit/tls/server.crt
return "${status}"
}
@@ -140,9 +145,8 @@ random_key() { head -c 32 /dev/urandom | base64 | tr -d '\n'; }
run_lane() {
local lane_json="$1"
local id profile runtime
local id runtime profile
id="$(jq -r '.id' <<<"${lane_json}")"
profile="$(jq -r '.composeProfile // empty' <<<"${lane_json}")"
runtime="$(jq -r '.springRuntime' <<<"${lane_json}")"
PROJECT="casmoke-${id}-${PROJECT_RUN_ID}"
@@ -161,10 +165,14 @@ run_lane() {
file="$(jq -r --arg k "${key}" '.composeFiles[$k]' "${CONTRACTS}")"
LANE_ARGS+=(-f "${REPO_ROOT}/${file}")
done < <(jq -r '.files[]' <<<"${lane_json}")
[[ -n "${profile}" ]] && LANE_ARGS+=(--profile "${profile}")
# The development stack's backing services carry capability profiles and the lane-only services
# their own, so a lane enables several. The list is the lane's, never a guess from its name.
while read -r profile; do
[[ -n "${profile}" ]] && LANE_ARGS+=(--profile "${profile}")
done < <(jq -r '.composeProfiles[]' <<<"${lane_json}")
# A fresh client secret per run, mode 0600, removed on teardown. The realm references it by name.
local secret_dir="${REPO_ROOT}/infra/keycloak/secrets"
local secret_dir="${REPO_ROOT}/compose/keycloak/secrets"
local secret_file="${secret_dir}/graphql-smoke-client-secret"
mkdir -p "${secret_dir}"
local client_secret; client_secret="$(random_secret)"
@@ -177,7 +185,7 @@ run_lane() {
# a private key in Git. The host name matters — the prod runtime connects with sslmode=verify-full,
# which checks the certificate against the name it dialled, so a certificate for anything but `db`
# fails exactly as a redirected connection would. That is the check, working.
local tls_dir="${REPO_ROOT}/infra/postgres/tls"
local tls_dir="${LANE_POSTGRES_TLS}"
if jq -e '.files | index("tls")' <<<"${lane_json}" >/dev/null; then
mkdir -p "${tls_dir}"
(
@@ -205,7 +213,7 @@ run_lane() {
# Same rule as the PostgreSQL one above and for the same reason: the notification platform's
# transport type has no plaintext member, so a relay without a certificate is one the platform
# cannot be configured to talk to. Generated per run, removed on teardown.
local mail_tls="${REPO_ROOT}/infra/mailpit/tls"
local mail_tls="${REPO_ROOT}/compose/mailpit/tls"
if jq -e '.services | index("mailpit")' <<<"${lane_json}" >/dev/null; then
mkdir -p "${mail_tls}"
(
@@ -232,7 +240,7 @@ run_lane() {
# interpolation reads the process environment and the project .env file, never a service's
# env_file. So the application got the generated password and the database got the literal
# default, and no lane whose overlay did not happen to restate the value could ever authenticate.
# shared-infra-local passed only because the local overlay restates it, which made the dev lane's
# shared-infra-local passed only because the local overlay (now compose.yaml) restated it, which made the dev lane's
# failure look like a dev-specific problem rather than the general one it is.
export POSTGRES_DB=ca_skeleton
export APP_DATASOURCE_USERNAME=ca_skeleton
@@ -323,7 +331,7 @@ run_lane() {
# The lane's own settings go into a generated overlay rather than into that file.
#
# env_file lists merge across overlays and the later file wins, so the developer's optional
# src/.env — declared by the local overlay, after the base — silently overrode the lane's values.
# src/.env — declared by the local overlay (now compose.yaml) — silently overrode the lane's values.
# local-messaging started Kafka, set APP_MESSAGING_BROKER=kafka, and was refused by the dependency
# validator for a broker it had supplied, because an empty value from a file nobody mentioned won
# the merge. An `environment:` block beats every env_file regardless of order, so the lane's
@@ -333,6 +341,10 @@ run_lane() {
# Written as a function, because a handoff lane rewrites it between phases: the same project and
# the same database, with the application recreated under a different activation environment.
local lane_overlay="${LANE_TMP}/lane-overrides.yml"
# The application's memory limit, when the lane needs more than the development stack's 512m.
# Only the lane that boots every capability at once does (the contract's appMemoryLimit says why).
local memory_limit
memory_limit="$(jq -r '.appMemoryLimit // empty' <<<"${lane_json}")"
write_lane_overlay() {
local phase_override="${1:-{\}}"
(
@@ -340,6 +352,10 @@ run_lane() {
{
echo "services:"
echo " app:"
if [[ -n "${memory_limit}" ]]; then
echo " mem_limit: ${memory_limit}"
echo " memswap_limit: ${memory_limit}"
fi
echo " environment:"
local entry
for entry in "${lane_environment[@]}"; do
@@ -550,13 +566,38 @@ run_lane() {
return 1
fi
# 4a. No container of the lane restarted and none was killed for memory.
#
# The application runs with `restart: unless-stopped`, so a container the kernel killed for
# exceeding its memory limit came back on its own. all-adapters did exactly that for a long time
# and failed only when the kill happened to land on a smoke request; every other run reported
# green over a container that had died and restarted under it (integration-r9, 2026-11-07). The
# checks above all ask the application a question, and a restarted application answers them, so
# the restart itself has to be the failure. The peak memory is recorded beside it, so a lane that
# is close to its limit is visible before it crosses it.
local container restarted=""
docker compose -p "${PROJECT}" "${LANE_ARGS[@]}" exec -T app cat /sys/fs/cgroup/memory.peak \
>"${LANE_EVIDENCE}/app-memory-peak-bytes.txt" 2>/dev/null || true
while read -r container; do
[[ -z "${container}" ]] && continue
docker inspect --format '{{.Name}} restarts={{.RestartCount}} oomKilled={{.State.OOMKilled}}' \
"${container}" >>"${LANE_EVIDENCE}/restarts.txt"
done < <(docker compose -p "${PROJECT}" "${LANE_ARGS[@]}" ps -a -q)
restarted="$(grep -v ' restarts=0 oomKilled=false$' "${LANE_EVIDENCE}/restarts.txt" || true)"
if [[ -n "${restarted}" ]]; then
echo "${id}: a container restarted or was killed for memory during the lane:" >&2
echo "${restarted}" >&2
return 1
fi
# 5. the manifest ties the evidence to the exact stack that produced it
jq -n \
--arg lane "${id}" --arg run "${RUN_ID}" --arg project "${PROJECT}" \
--arg runtime "${runtime}" --arg profile "${profile}" \
--arg runtime "${runtime}" \
--argjson profiles "$(jq '.composeProfiles' <<<"${lane_json}")" \
--argjson services "$(jq '.services' <<<"${lane_json}")" \
'{lane:$lane, runId:$run, project:$project, springRuntime:$runtime,
composeProfile:(if $profile=="" then null else $profile end), services:$services}' \
composeProfiles:$profiles, services:$services}' \
>"${LANE_EVIDENCE}/manifest.json"
echo "== ${id}: passed"
@@ -582,11 +623,22 @@ echo "running ${total} blocking lane(s), zero-skip"
# script reported that all six had passed. A wrapper whose own success message is a false green is
# worse than no wrapper, and nothing else here would have caught it: the count came from the
# contract and the exit status from the one lane that did run.
#
# Each lane runs in a subshell with `set -e` on and its status read afterwards, never as an `if`
# condition. Bash ignores `set -e` for every command run as part of an `if` condition, functions and
# subshells included, so `if ( run_lane ... )` turned every step that relied on it into a step whose
# failure was ignored. The image build was one: a build that failed left the lane to start the
# previous run's image, and all eighteen lanes reported green on code the build had refused
# (2026-11-07). --lane mode calls run_lane directly and was not affected.
RAN_LANES=0
while read -r -u 3 lane_json; do
[[ -z "${lane_json}" ]] && continue
RAN_LANES=$((RAN_LANES + 1))
if ( trap cleanup_lane EXIT; run_lane "${lane_json}" ); then :; else
set +e
( set -e; trap cleanup_lane EXIT; run_lane "${lane_json}" )
lane_status=$?
set -e
if [[ ${lane_status} -ne 0 ]]; then
FAILED_LANES+=("$(jq -r '.id' <<<"${lane_json}")")
fi
done 3<<<"${blocking}"
+19 -9
View File
@@ -1,7 +1,7 @@
#!/usr/bin/env bash
# The static half of the Compose contract: every lane renders, and renders exactly what it claims.
#
# Seven things are checked, and each exists because assuming it cost something:
# Nine things are checked, and each exists because assuming it cost something:
#
# 1. the Compose version, because `!override` is what stops the dev overlay's tmpfs merging with
# the base's and colliding with a bind mount, and it needs 2.24.4;
@@ -22,12 +22,15 @@
# lanes ran Redis open and the application anonymous, and the two startup warnings that trade
# prints failed the "startup is silent" check of every such lane (r3-J). Lowering that warning
# would hide the same trade in production; the lane has to look like a deployment instead.
# 8. a lane's appMemoryLimit, when it has one, is a Compose memory size, because the smoke wrapper
# writes it into the application's mem_limit and a malformed one fails only at `up`.
# 9. the Keycloak realm artifact carries no key Keycloak refuses (below the lane loop).
#
# Static only. Nothing starts here; scripts/run-compose-runtime-smoke.sh owns that.
set -euo pipefail
REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
CONTRACTS="${REPO_ROOT}/src/config/runtime/compose-profile-contracts.json"
CONTRACTS="${REPO_ROOT}/src/app-bootstrap/compose-lanes/compose-profile-contracts.json"
FAILURES=0
fail() { echo " FAIL: $*" >&2; FAILURES=$((FAILURES + 1)); }
@@ -118,7 +121,6 @@ lane_count="$(jq '.lanes | length' "${CONTRACTS}")"
for index in $(seq 0 $((lane_count - 1))); do
lane="$(jq -c ".lanes[${index}]" "${CONTRACTS}")"
id="$(jq -r '.id' <<<"${lane}")"
profile="$(jq -r '.composeProfile // empty' <<<"${lane}")"
runtime="$(jq -r '.springRuntime' <<<"${lane}")"
expected="$(jq -r '.services | sort | join(",")' <<<"${lane}")"
@@ -130,7 +132,9 @@ for index in $(seq 0 $((lane_count - 1))); do
done < <(jq -r '.files[]' <<<"${lane}")
profile_args=()
[[ -n "${profile}" ]] && profile_args=(--profile "${profile}")
while read -r profile; do
[[ -n "${profile}" ]] && profile_args+=(--profile "${profile}")
done < <(jq -r '.composeProfiles[]' <<<"${lane}")
# 2. exact service set
# stderr goes to a file rather than into the list. It used to be merged with `2>&1`, so Compose's
@@ -223,20 +227,26 @@ for index in $(seq 0 $((lane_count - 1))); do
done < <(redis_authentication_problems "${lane}" "${model}")
fi
# 8. the lane's own memory limit, when it sets one.
memory_limit="$(jq -r '.appMemoryLimit // empty' <<<"${lane}")"
if [[ -n "${memory_limit}" && ! "${memory_limit}" =~ ^[1-9][0-9]*[kmg]$ ]]; then
fail "${id}: appMemoryLimit '${memory_limit}' is not a Compose memory size such as 1g"
fi
[[ ${FAILURES} -eq 0 ]] && echo "${id}: ${expected} @ ${runtime}"
done
# 8. the Keycloak realm artifact deserializes into Keycloak's own representation.
# 9. the Keycloak realm artifact deserializes into Keycloak's own representation.
#
# Keycloak rejects unknown fields rather than ignoring them, so one annotation key anywhere in the
# tree fails the whole import, the container exits 1, and every lane that needs an identity provider
# fails on Keycloak instead of on what it was testing. This cost two lane runs to find, once for
# `_comment` on the realm and once for `_flowComment` on a client, because the second was invisible
# until the first was fixed. Rationale for that artifact lives in infra/keycloak/README.md.
realm="${REPO_ROOT}/infra/keycloak/realms/ca-skeleton-realm.json"
# until the first was fixed. Rationale for that artifact lives in compose/keycloak/README.md.
realm="${REPO_ROOT}/compose/keycloak/realms/ca-skeleton-realm.json"
if [[ -f "${realm}" ]]; then
if ! jq empty "${realm}" >/dev/null 2>&1; then
fail "infra/keycloak/realms/ca-skeleton-realm.json is not valid JSON"
fail "compose/keycloak/realms/ca-skeleton-realm.json is not valid JSON"
else
annotations="$(jq -r '[paths(scalars, objects, arrays) | .[-1] | select(type == "string") | select(startswith("_"))] | unique | join(", ")' "${realm}")"
if [[ -n "${annotations}" ]]; then
@@ -249,4 +259,4 @@ if [[ ${FAILURES} -gt 0 ]]; then
echo "verify-compose-profile-contracts: ${FAILURES} lane(s) do not match the contract" >&2
exit 1
fi
echo "verify-compose-profile-contracts: all ${lane_count} lanes match src/config/runtime/compose-profile-contracts.json"
echo "verify-compose-profile-contracts: all ${lane_count} lanes match src/app-bootstrap/compose-lanes/compose-profile-contracts.json"
+2 -2
View File
@@ -84,7 +84,7 @@ echo "=== [actual-topology] provider environments"
#
# The selector names the contract's class. `--tests '*Shard*'` was satisfied by the hermetic
# ShardKeyAnalyzerTest, so "sharded topology" was certified by a unit test that never opened a
# connection. Which classes count is `src/config/mongodb/release-contracts.json`, and
# connection. Which classes count is `src/adapter/outbound/persistence-mongo/release/release-contracts.json`, and
# MongoReleaseEvidenceVerifier checks the JUnit XML rather than the exit code.
if [[ -n "${MONGODB_SHARDED_URI:-}" ]]; then
# Not promoted. `mongoShardedTest` is declared in release-contracts.json under
@@ -94,7 +94,7 @@ if [[ -n "${MONGODB_SHARDED_URI:-}" ]]; then
# a silent skip: an operator who set it expected a qualification to run.
echo "sharded topology is experimental and has no registered lane;" >&2
echo " MONGODB_SHARDED_URI was set but mongoShardedTest does not exist." >&2
echo " See experimental_contracts in src/config/mongodb/release-contracts.json." >&2
echo " See experimental_contracts in src/adapter/outbound/persistence-mongo/release/release-contracts.json." >&2
FAILED+=("actual-topology:sharded-not-promoted")
else
echo "actual-topology(sharded): no MONGODB_SHARDED_URI"
+2 -2
View File
@@ -155,8 +155,8 @@ mkdir -p "${MANIFEST_DIR}"
echo " \"commitDirty\": $( [[ -n "$(git -C "${REPO_ROOT}" status --porcelain)" ]] && echo true || echo false ),"
echo " \"serverImage\": \"${MONGODB_IMAGE:-mongo:8.0.16}\","
echo " \"generatedAt\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\","
echo " \"contractManifest\": \"src/config/mongodb/release-contracts.json\","
echo " \"contractManifestSha256\": \"$(sha256sum "${REPO_ROOT}/src/config/mongodb/release-contracts.json" | cut -d' ' -f1)\""
echo " \"contractManifest\": \"src/adapter/outbound/persistence-mongo/release/release-contracts.json\","
echo " \"contractManifestSha256\": \"$(sha256sum "${REPO_ROOT}/src/adapter/outbound/persistence-mongo/release/release-contracts.json" | cut -d' ' -f1)\""
echo "}"
} > "${MANIFEST_DIR}/promotion.json"
echo "promotion manifest: ${MANIFEST_DIR}/promotion.json"
+2 -2
View File
@@ -155,8 +155,8 @@ APP_REDIS_TIMEOUT_SCRIPT=1s
# reads the password from <VARIABLE> and authenticates as <acl-account>. With the application
# reference empty and anonymous access not accepted, the application refuses to start while Redis
# is on; with the advanced one empty, scripts run as the application account and startup warns. The
# Compose Redis lanes connect as the fixture accounts of infra/redis-sdk/acl/lane-fixture-accounts.acl (the
# Redis comment in src/config/runtime/compose-profile-contracts.json).
# Compose Redis lanes connect as the fixture accounts of compose/redis/acl/lane-fixture-accounts.acl (the
# Redis comment in src/app-bootstrap/compose-lanes/compose-profile-contracts.json).
APP_REDIS_AUTHENTICATION_ADVANCED_CREDENTIAL_REFERENCE=
APP_REDIS_AUTHENTICATION_ANONYMOUS_ACCESS_ACCEPTED=false
APP_REDIS_AUTHENTICATION_CREDENTIAL_REFERENCE=
+5
View File
@@ -46,6 +46,11 @@ COPY gradle/ gradle/
COPY gradle.properties ./
COPY config/ ./config/
COPY --parents settings.gradle build.gradle **/build.gradle **/gradle.lockfile ./
# The data a leaf's build script reads while Gradle configures it: the JPA leaf's readiness cards
# decide which scenarios each readiness lane requires. Since 2026-11-07 such data lives in the
# release/ folder of the leaf that owns it rather than under config/, and without this line that
# leaf fails to configure in the dependency-resolution stage below.
COPY --parents **/release/*.yaml **/release/*.json ./
# The convention plugins, whole. The glob above copies files named build.gradle and gradle.lockfile,
# which picks up build-logic's own build script and misses the precompiled script plugins beside it —
# so settings.gradle's `includeBuild('build-logic')` resolved against a build that declared no
-159
View File
@@ -1,159 +0,0 @@
# syntax=docker/dockerfile:1.7-labs@sha256:b99fecfe00268a8b556fad7d9c37ee25d716ae08a5d7320e6d51c4dd83246894
# =============================================================================
# sample-portfolio standalone demo image — twin of src/Dockerfile.
#
# Builds and runs the REFERENCE app (SamplePortfolioApplication), not the
# production composition root (CaSkeletonApplication) that src/Dockerfile builds.
# The sample is the demo-friendly entrypoint: its application.yml self-provides
# defaults for every env placeholder, so what it needs to boot is a demo profile
# and a reachable PostgreSQL (datasource + Flyway sample migrations).
#
# The profile is not baked in. The demo accounts (a published admin password) start only under an
# explicitly active `demo`, `local` or `test` profile (SampleDemoAccountsProductionGuard), and an
# image that defaulted to one would carry them into any deployment that ran it as is. Without
# SPRING_PROFILES_ACTIVE the container stops with exit code 71 and says so.
#
# Build (no build-args required — this is a disposable demo, not a release artifact):
# docker build -f src/Dockerfile.sample src/ -t ca-sample:local
#
# Run (point APP_DATASOURCE_URL at a reachable Postgres; localhost default shown):
# docker run --rm -p 8080:8080 -p 9001:9001 \
# -e SPRING_PROFILES_ACTIVE=demo \
# -e APP_DATASOURCE_URL=jdbc:postgresql://host.docker.internal:5432/ca_skeleton \
# ca-sample:local
#
# The multi-stage build, --parents descriptor glob, STRICT lock verification,
# non-root user, read-only-root-fs writable mounts, and JVM container ergonomics
# are all identical to src/Dockerfile — only the bootJar target differs.
#
# Two files rather than one with a COMPOSITION=sample argument: the release image refuses to build
# without version and source metadata, and folding a zero-argument demo into it would make that
# refusal conditional. The part that must not drift — the dependency stage's COPY lines — is held
# equal by DeveloperExperienceContractTest.
# =============================================================================
# Demo defaults so the image builds with zero build-args. Two format constraints from the root
# build.gradle configuration guard (feature-build-release-supply-chain-contract D1/D9):
# - RELEASE_VERSION must be bare MAJOR.MINOR.PATCH — no pre-release/build suffix (build.gradle L21).
# The "-sample" marker therefore lives only on BUILD_VERSION, which is a label, not a gradle prop.
# - GIT_SHA must be 7-40 hex chars (build.gradle L35); 0000000 is the placeholder.
ARG RELEASE_VERSION=0.0.0
ARG BUILD_VERSION=0.0.0-sample
ARG GIT_SHA=0000000
ARG SOURCE_URL=https://example.invalid/ca-tmpl-sample
# ---- Stage 1: builder -------------------------------------------------------
# Uses the full JDK only in the build stage, never in the final image.
FROM eclipse-temurin:21-jdk-jammy@sha256:801b7e1a9c4befaf82bf9a2a58025ef43a7694bbc84779187ad0524d84742772 AS builder
ARG RELEASE_VERSION
ARG GIT_SHA
WORKDIR /build/src
# Copy the Gradle wrapper and every module's build descriptor + dependency lockfile FIRST,
# so the expensive dependency-resolution layer is cached and only re-runs when a build.gradle
# or gradle.lockfile changes (D8). `--parents` preserves each file's directory structure, so a
# single structure-preserving glob replaces a per-module COPY list: new modules are picked up
# automatically and this stage never drifts out of sync with settings.gradle.
# (Requires the labs Dockerfile frontend — see the `# syntax` directive at the top of this file.)
COPY gradlew ./
COPY gradle/ gradle/
COPY gradle.properties ./
COPY config/ ./config/
COPY --parents settings.gradle build.gradle **/build.gradle **/gradle.lockfile ./
# The convention plugins, whole — see src/Dockerfile. Without them settings.gradle's
# includeBuild('build-logic') has no version catalog and no plugins, and this stage failed before
# resolving anything (07-04). DeveloperExperienceContractTest holds these COPY lines equal to the
# release image's.
COPY build-logic/ ./build-logic/
# Resolve every module configuration in STRICT mode (no --write-locks in a demo build either).
RUN test -n "${RELEASE_VERSION}" \
&& test -n "${GIT_SHA}" \
&& ./gradlew verifyDependencyLocks --no-daemon --quiet \
-PreleaseVersion="${RELEASE_VERSION}" -PgitRevision="${GIT_SHA}"
# Copy full source and stage the executable sample JAR at Gradle's declared Docker output path.
COPY . .
RUN ./gradlew :sample-portfolio:stageDockerJar --no-daemon -x test \
-PreleaseVersion="${RELEASE_VERSION}" -PgitRevision="${GIT_SHA}"
# ---- Layer extraction -------------------------------------------------------
# Identical to src/Dockerfile — see the long note there. Kept in sync because the header of this
# file says the builder stages are, and a demo image whose layout has drifted from the release image
# stops being a demo of the release image. Absolute paths for the same contract-test reason.
RUN java -Djarmode=tools \
-jar /build/src/sample-portfolio/build/docker/application.jar \
extract --layers --destination /build/src/sample-portfolio/build/docker/extracted
# ---- Stage 2: runtime image -------------------------------------------------
# JRE-only slim image (no full JDK in the demo image either).
FROM eclipse-temurin:21-jre-jammy@sha256:199aebeb3adcde4910695cdebfe782ada38dadb6cc8013159b58d3724451befd AS runtime
ARG BUILD_VERSION
ARG GIT_SHA
ARG SOURCE_URL
# OCI image labels. Unlike the release image (src/Dockerfile), the demo image does NOT hard-fail
# on missing metadata — the ARG defaults above keep it buildable with no build-args.
LABEL org.opencontainers.image.title="caskeleton-sample" \
org.opencontainers.image.description="ca-tmpl sample-portfolio reference/demo application" \
org.opencontainers.image.source="${SOURCE_URL}" \
org.opencontainers.image.revision="${GIT_SHA}" \
org.opencontainers.image.version="${BUILD_VERSION}"
# ---- Locale / timezone ------------------------------------------------------
ENV TZ=UTC \
LANG=C.UTF-8 \
LC_ALL=C.UTF-8
# ---- Writable HOME under read-only root fs ----------------------------------
ENV HOME=/tmp
# ---- JVM ergonomics ---------------------------------------------------------
# Identical to src/Dockerfile: container-aware heap, fail-fast on OOM, heap dump to a
# writable mount, and Tomcat temp redirected to /tmp for a read-only root filesystem.
ENV JAVA_TOOL_OPTIONS="\
-XX:MaxRAMPercentage=75 \
-XX:+UseContainerSupport \
-XX:+ExitOnOutOfMemoryError \
-XX:+HeapDumpOnOutOfMemoryError \
-XX:HeapDumpPath=/var/tmp/heap \
-Dserver.tomcat.basedir=/tmp"
# ---- Filesystem layout (read-only root filesystem) --------------------------
# At runtime /var/tmp/heap and /tmp MUST be writable mounts (tmpfs/emptyDir).
RUN mkdir -p /var/tmp/heap && chmod 1777 /var/tmp/heap
# ---- Non-root user ----------------------------------------------------------
RUN groupadd --system --gid 1000 app \
&& useradd --system --uid 1000 --gid app --no-create-home --shell /usr/sbin/nologin app
WORKDIR /app
# ---- Application layers -----------------------------------------------------
# One COPY per Spring Boot layer, least- to most-frequently-changed, matching src/Dockerfile.
COPY --from=builder --chown=app:app /build/src/sample-portfolio/build/docker/extracted/dependencies/ ./
COPY --from=builder --chown=app:app /build/src/sample-portfolio/build/docker/extracted/spring-boot-loader/ ./
COPY --from=builder --chown=app:app /build/src/sample-portfolio/build/docker/extracted/snapshot-dependencies/ ./
COPY --from=builder --chown=app:app /build/src/sample-portfolio/build/docker/extracted/application/ ./
USER app
# ---- Ports ------------------------------------------------------------------
# 8080 — application HTTP port
# 9001 — management / actuator port
EXPOSE 8080 9001
# ---- Health check -----------------------------------------------------------
# Actuator readiness probe on the management port (9001). Ignored by Kubernetes,
# which uses its own probes — kept for docker/compose parity with src/Dockerfile.
HEALTHCHECK --interval=30s --timeout=5s --start-period=60s --retries=3 \
CMD wget --no-verbose --tries=1 --spider \
http://localhost:9001/actuator/health/readiness || exit 1
# ---- Entrypoint -------------------------------------------------------------
# mainClass (SamplePortfolioApplication) is baked into the bootJar manifest and survives the
# extraction into the thin application.jar.
ENTRYPOINT ["java", "-jar", "application.jar"]
+15 -17
View File
@@ -26,11 +26,11 @@ Checkstyle은 **포매터가 표현할 수 없는 것만** — 네이밍과 몇
| `qualityCheck` | 모든 leaf의 SpotBugs + FindSecBugs를 실행 |
| `configContractCheck` | `:app-bootstrap:verifyEnvKeys`로 환경 설정 계약을 검사 |
| `qualificationCheck` | 전체 기동(system) 레인과 보조 source set Checkstyle을 실행 |
| `integrationCheck` | 선언된 strict integration lane(sample 포함)을 실행. 대부분 container runtime이 필요. 입력이 필요한 lane(Redis topology: `-Predis.topology.mode`, AWS: 보호 자격 증명 env)은 입력이 없으면 빠지고 집계가 그 이유를 출력 |
| `integrationCheck` | 선언된 strict integration lane을 실행. 대부분 container runtime이 필요. 입력이 필요한 lane(Redis topology: `-Predis.topology.mode`, AWS: 보호 자격 증명 env)은 입력이 없으면 빠지고 집계가 그 이유를 출력 |
| `performanceCheck` | 선언된 strict performance lane(부하·종료·pool·자원 상한)을 실행. 실서버·container가 필요. 상한은 매번 단언하고 끄는 속성이 없다(`-Pperformance.assertions.enabled`가 `true`가 아니면 실패, skip된 테스트가 있어도 실패). `integration-main.yml` `performance-check`가 main·nightly에 같은 명령으로 돌림 |
| `verifyStrictLaneStages` | `--dry-run` 전용. `explicitOnly`가 아닌 strict lane이 workflow가 실제 실행하는 단계(`ci`·`:sample-portfolio:check`·`mainCheck`·`integrationCheck`·`performanceCheck`·`releaseCheck`) 중 하나의 계획에 있는지, 각 단계를 workflow가 `--dry-run` 없이 실행하는지 검사. Gradle이 작업을 돌리지 않는 명령(`--dry-run`·`-v`·`--help` 등)과, 실패해도 단계가 실패하지 않을 수 있거나(`\|\| true`, pipefail 없는 파이프, `if` 조건 등) 돌지 않을 수 있거나(조건부 `exit 0` 뒤, 요청으로만 시작하는 workflow, `paths` 필터로만 시작하는 workflow, `releaseCheck` 밖의 단계를 태그 push·`release`로만 시작하는 workflow 등) 검사가 읽지 않는(`\|\| exit 1`, `{ }` 안 등) 명령은 실행으로 세지 않는다. 자세한 목록은 `build-logic/README.md`. PR 게이트가 돌림 |
| `verifyStrictLaneStages` | `--dry-run` 전용. `explicitOnly`가 아닌 strict lane이 workflow가 실제 실행하는 단계(`ci`·`mainCheck`·`integrationCheck`·`performanceCheck`·`releaseCheck`) 중 하나의 계획에 있는지, 각 단계를 workflow가 `--dry-run` 없이 실행하는지 검사. Gradle이 작업을 돌리지 않는 명령(`--dry-run`·`-v`·`--help` 등)과, 실패해도 단계가 실패하지 않을 수 있거나(`\|\| true`, pipefail 없는 파이프, `if` 조건 등) 돌지 않을 수 있거나(조건부 `exit 0` 뒤, 요청으로만 시작하는 workflow, `paths` 필터로만 시작하는 workflow, `releaseCheck` 밖의 단계를 태그 push·`release`로만 시작하는 workflow 등) 검사가 읽지 않는(`\|\| exit 1`, `{ }` 안 등) 명령은 실행으로 세지 않는다. 자세한 목록은 `build-logic/README.md`. PR 게이트가 돌림 |
| `ci` | PR 게이트: 모든 leaf `check`(API surface 검사 포함, 소유자 결정 20) + `architectureCheck` + `qualityCheck` |
| `mainCheck` | main 단계: `configContractCheck` + `qualificationCheck` + sample web 계약 + sample 전체 기동(`:sample-portfolio:systemTest`) + `verifyPublicPathSnapshot` + 전송·메시징 qualification 레인 + 각 leaf의 `mainCheck`(문서 대조 레인 `*DocumentContractTest`, objectstorage MinIO 레인) |
| `mainCheck` | main 단계: `configContractCheck` + `qualificationCheck` + `verifyPublicPathSnapshot` + 전송·메시징 qualification 레인 + 각 leaf의 `mainCheck`(문서 대조 레인 `*DocumentContractTest`, objectstorage MinIO 레인) |
| `releaseCheck` | tag 전용 검사: `verifyReleaseProvenance` + `verifyPublicPathSnapshot`(`ci`를 다시 돌리지 않음) |
따라서 로컬에서 한 모듈만 수정했다면 `./gradlew :domain-core:check`처럼 focused task를
@@ -46,10 +46,10 @@ Checkstyle은 **포매터가 표현할 수 없는 것만** — 네이밍과 몇
### Local bootstrap
`scripts/bootstrap-local.sh [profile]`(저장소 루트)은 compile → Docker 확인 → DB 기동 대기 →
`scripts/bootstrap-local.sh`(저장소 루트)은 compile → Docker 확인 → DB 기동 대기 →
app 기동(Flyway 포함) → health smoke를 순서대로 실행합니다(예전 `./gradlew bootstrap`, 리뷰
BUILD-O3-5로 build-logic 플러그인에서 스크립트로 옮김).
DB와 app lifecycle은 저장소 루트의 base/local Compose 조합이 소유하며, app startup Flyway가
DB와 app lifecycle은 저장소 루트의 개발 compose 파일 `compose.yaml`(`db`는 `jpa` profile)이 소유하며, app startup Flyway가
끝나 public health endpoint가 준비되어야 다음 단계로 넘어갑니다. `src/.env.example`은 커밋된
env 계약이고 `src/.env`는 로컬 실행 입력입니다. `verifyEnvKeys`는 example/registry/shipped YAML을
함께 검사합니다.
@@ -296,8 +296,9 @@ Kafka 없이 기동합니다. 나머지 기능은 `app-bootstrap/build.gradle`
### Compose와 런타임 스모크
- **Docker Compose 최소 버전 `2.24.4`.** SSOT는 `src/config/runtime/compose-profile-contracts.json`
이고, 정본 스크립트가 검증합니다.
- **Docker Compose 최소 버전 `2.24.4`.** SSOT는 `src/app-bootstrap/compose-lanes/compose-profile-contracts.json`
이고, 정본 스크립트가 검증합니다. lane은 저장소 루트 `compose.yaml`(개발 환경)을 바탕으로 쓰고, lane에만
필요한 overlay·smoke client·스키마 적용은 `src/app-bootstrap/compose-lanes/`에 있습니다.
- 진입점은 둘뿐이고, 그 둘만이 증거입니다. 워크플로에 명령 일부를 인라인하면 one-shot 없이 도는 레인이
초록으로 보고됩니다.
@@ -305,9 +306,9 @@ Kafka 없이 기동합니다. 나머지 기능은 `app-bootstrap/build.gradle`
# 정적: profile별 정확한 service set, 병합된 모델 전체, mount target 유일성
./scripts/verify-compose-profile-contracts.sh
# 동적: 15개 blocking 레인을 zero-skip으로. create → up --wait → 필수 one-shot →
# sanitized evidence → 고유 project teardown
./scripts/run-compose-runtime-smoke.sh --matrix src/config/runtime/compose-profile-contracts.json
# 동적: 계약의 blocking 레인을 zero-skip으로. create → up --wait → 필수 one-shot →
# 컨테이너 재시작·OOM 0 확인 → sanitized evidence → 고유 project teardown
./scripts/run-compose-runtime-smoke.sh --matrix src/app-bootstrap/compose-lanes/compose-profile-contracts.json
```
`--lane <id>`는 실패 재현용이고, 레인 하나가 초록인 것은 matrix가 통과했다는 증거가 아닙니다.
@@ -317,7 +318,7 @@ Kafka 없이 기동합니다. 나머지 기능은 `app-bootstrap/build.gradle`
Kafka·Redis는 위 "기능 추가 = 한 줄 + env" 표의 한 줄로 고릅니다. 모듈이 있으면 켜지고, 없으면 그
포트를 구현하는 bean이 아예 없습니다. 아래는 모듈을 고른 뒤 동작을 고르는 키입니다.
- **`APP_CACHE_REDIS_ENABLED`** — deprecated(2026-11-30 제거 예정). 읽는 곳은 `sample-portfolio`뿐이고,
- **`APP_CACHE_REDIS_ENABLED`** — deprecated(2026-11-30 제거 예정). 읽는 곳이 없고,
기본 조립에서 Redis를 켜고 끄는 것은 `APP_REDIS_ENABLED`입니다.
- **`APP_CACHE_CANONICAL_DEFAULT_PROVIDER`** — canonical default semantic region 선택.
`disabled`(기본) | `redis`. `redis`는 canonical Redis CACHE role binding을 함께 요구합니다.
@@ -359,10 +360,7 @@ app:
- 기존 `APP_OUTBOUND_HTTP_*`와 `app.outbound.http.*`는 canonical 설정이 아닙니다. 루트 `src/.env`,
`app-bootstrap`의 application YAML, env-key registry에서 제거됐으며 canonical composition에
입력하면 상태와 무관하게 기동을 거부합니다.
- 다만 `sample-portfolio`의 application YAML에는 legacy facade를 시연하기 위해 15개 키가 남아
있습니다. 이 모듈은 fixture/reference consumer이고 production 의존성이 아니며, 그 YAML은
`:app-bootstrap:verifyEnvKeys`가 검사하는 세 파일에 포함되지 않습니다. "제거됐다"는 문장이 저장소 전체를
가리킨다고 읽히지 않도록 범위를 명시합니다.
- 그 키를 시연하던 샘플 모듈의 YAML은 2026-11-07 샘플과 함께 지웠습니다. 이제 저장소 어디에도 남아 있지 않습니다.
- legacy JDK facade가 필요한 fork만 canonical composition 밖에서
`OutboundHttpSettings.bindLegacy(Binder)`와 legacy configuration을 명시적으로 import합니다.
timeout/retry/CB/response-size 설정은 그 migration API 내부 계약일 뿐 canonical provider
@@ -535,11 +533,11 @@ migration/vendor 계약의 증거로 사용하지 않습니다. 멱등성 provid
`disabled`(기본)나 `redis`로 둡니다. `postgresql`은 H2 data source에서 기동을 거부합니다.
`dev` 를 호스트에서 띄우려면(`SPRING_PROFILES_ACTIVE=dev`) PostgreSQL 이 필요합니다.
`docker-compose.local.yml` 의 `db` 서비스가 루프백(`127.0.0.1:5433`)에만 게시하며, 이 주소가
`compose.yaml` 의 `db` 서비스(`jpa` profile)가 루프백(`127.0.0.1:5433`)에만 게시하며, 이 주소가
아래 `APP_DATASOURCE_URL` 의 커밋된 기본값입니다. 저장소 루트에서 실행합니다.
```bash
docker compose -f docker-compose.yml -f docker-compose.local.yml up -d --wait db
docker compose up -d --wait db
```
컨테이너로 띄우는 `scripts/bootstrap-local.sh` 경로는 이 호스트 포트를 쓰지 않습니다. compose 가 app
+2 -2
View File
@@ -114,7 +114,7 @@ application/platform namespace split.
`INBOUND_ADAPTERS_DO_NOT_DEPEND_ON_OUTBOUND_ADAPTERS`, 일반 `..adapter.inbound..` 규칙이 이
모듈을 자동 커버 — per-module 규칙 추가 불필요).
- 프로덕션 feature 쿼리/뮤테이션을 스켈레톤에 두는 것 — health 표면만 (web 의
`HealthcheckController` 와 동일 원칙). feature 스키마/컨트롤러/매퍼는 sample 모듈이 소유한다.
`HealthcheckController` 와 동일 원칙). feature 스키마/컨트롤러/매퍼는 그 기능을 가진 서비스가 소유한다.
- 모듈별 `yml` — 설정은 프레임워크 `spring.graphql.*` 로 composition-root `application.yml` 에 산다.
## Error mapping (`Category → ErrorType`)
@@ -139,7 +139,7 @@ DataLoader 키 실패는 등록된 `ApiErrorCode` 만 싣는다(`GraphQlBatchLoa
- **도메인 예외 매핑**: adopter 는 자신의 `DataFetcherExceptionResolver` 를 추가하거나
`ApiErrorCarrier` 를 사용해 안정적 코드로 매핑할 수 있다.
현재 sample 에 feature GraphQL schema/controller/resolver 가 있다고 가정하지 않는다. 이 leaf 는
템플릿에는 feature GraphQL schema/controller/resolver 가 없다. 이 leaf 는
health 스키마만 소유한다.
## 구현된 플랫폼 범위 — 등급으로 말한다

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