Files
clean-architecture-backend-…/scripts/verify-compose-profile-contracts.sh
T
DongHyeonka 50cd7154d0 refactor(compose)!: compose 파일을 개발 환경 하나와 lane fixture로 나눈다
문제:
- 루트 compose 6개와 infra/ 아래 12개가 개발 환경, 테스트 lane fixture,
  보조 파일을 가리지 않고 섞여 있다. 이름 모양도 셋이다.
- README 빠른 시작 scripts/bootstrap-local.sh는 docker-compose.yml과
  .local.yml만 합친 뒤, 둘 어디에도 없는 db 서비스를 띄우려다 멈춘다.
- compose smoke all-adapters lane은 앱이 mem_limit 512m를 넘어 커널에
  죽고(OOM), restart: unless-stopped로 다시 떠서 죽는 때가 smoke 요청과
  겹칠 때만 실패한다. smoke는 재시작을 보지 않아 나머지 실행은 거짓 통과다.

고른 방법(소유자 결정 2026-11-07):
- 루트에 개발용 compose.yaml 하나. app(local 런타임)과 뒷단 서비스를
  capability profile(jpa, redis, kafka, mongo, objectstorage, auth, mail)로
  고른다. 마운트하는 보조 파일은 compose/(keycloak, minio init, Redis ACL,
  mailpit 인증서 폴더).
- lane fixture는 lane을 가진 leaf로: dev·prod-smoke·tls overlay, fileserver
  overlay, smoke·스키마 적용 서비스(lane-services.yaml)와 스크립트, lane
  계약 JSON → src/app-bootstrap/compose-lanes/. Redis topology →
  redis-sdk/compose/, NFS → fileserver/compose/nfs/. infra/는 없어진다.
- 계약의 composeProfile(문자열)을 composeProfiles(목록)로 바꾼다. lane이
  backing profile과 lane profile을 함께 켠다. 18 lane의 서비스 집합은
  전과 같다(verify-compose-profile-contracts.sh가 정확히 대조).
- smoke: lane이 끝나기 전에 그 project의 모든 컨테이너가 재시작 0,
  OOMKilled false인지 보고 아니면 실패한다. 앱의 memory.peak를 증거로
  남긴다. all-adapters만 appMemoryLimit 1g(계약 칸, smoke가 overlay에 씀).
- bootstrap-local.sh는 compose.yaml로 db와 app을 띄운다(인자 없음).
- 개발 compose와 lane 바탕이 같은 파일이라, app healthcheck는 모든
  런타임에서 답하는 관리 포트 readiness로 둔다.
버린 대안: lane을 Testcontainers로 옮기기(설계 다-2, 별도 판단), lane마다
기본 메모리를 올리기(배포 기본값 512m 계약을 흐림).

위험·한계:
- 개발 compose의 app이 src/.env를 읽으므로, 개발자 src/.env가 dev·prod
  lane에도 들어간다. lane 값은 생성 overlay의 environment가 이기고, CI에는
  src/.env가 없다.
- MinIO 이미지 기본값이 compose.yaml과 lane-services.yaml 두 곳에 있다
  (YAML anchor는 파일을 넘지 못한다). ComposeMinioImageMatchesEvidenceTest가
  둘 다 evidence digest와 대조한다.
- env 키 검사(verifyEnvKeys)는 compose.yaml과 lane overlay를 읽고
  lane-services.yaml(smoke client 변수)은 뺀다.

검증(desktop, 트리 6d1e9f9d → 주석·문서만 고친 d0703901, ~/t1-layout-logs/):
- verify-compose-profile-contracts.sh rc=0 (18 lane 정확히 일치)
- :app-bootstrap:check :app-bootstrap:documentContractTest
  :app-bootstrap:verifyEnvKeys와 objectstorage·cache-redis·redis-sdk·
  redis-runtime·fileserver·composition:fileserver-platform check rc=0
- :app-bootstrap:integrationTest(ComposeMergeCharacterizationTest 포함),
  :adapter:outbound:cache-redis:redisContainerContractTest rc=0
- -p build-logic check rc=0, :verifyStrictLaneStages --dry-run rc=0
- scripts/run-compose-runtime-smoke.sh --matrix(18 lane) rc=0, 794초.
  모든 lane 컨테이너 재시작 0·OOMKilled false. 앱 memory.peak 최고
  all-adapters 532MiB(512m 한도를 넘는 값이라 1g의 근거), 나머지 244~422MiB
- scripts/bootstrap-local.sh rc=0(db·app 기동, /api/healthcheck 200 UP).
  기준 ac03192d의 base+local 조합은 config --services가 app뿐이고
  up --wait db가 "no such service: db"로 rc=1
- 정리할 때 `docker compose down`은 profile 서비스(db)를 남겨
  README·compose.yaml 안내를 `--profile '*' down`으로 고치고 다시 확인
- 주석·문서 수정 뒤 :app-bootstrap:repositoryContractTest
  :app-bootstrap:documentContractTest, verify-compose rc=0

Refs: design-docs repo-structure/README.md 3.1, repo-structure/01-backend-layout.md 6.3
BREAKING CHANGE: 루트 docker-compose*.yml과 infra/가 없어지고 compose.yaml(profile)·compose/·leaf 안 lane fixture로 옮겨졌다. lane 계약은 src/app-bootstrap/compose-lanes/compose-profile-contracts.json, composeProfile → composeProfiles. docs/upgrade/2026-11-maturity-review.md B-51.
2026-11-07 12:52:36 +09:00

263 lines
15 KiB
Bash
Executable File

#!/usr/bin/env bash
# The static half of the Compose contract: every lane renders, and renders exactly what it claims.
#
# 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;
# 2. the exact service set per lane — exact, not a superset, because a lane that quietly gains a
# service is a lane whose evidence describes a different stack than the one that ran;
# 3. the rendered SPRING_PROFILES_ACTIVE, because a Compose profile selects services and says
# nothing about which environment the application thinks it is in;
# 4. mount-target uniqueness in the merged model, because that collision is exactly what made the
# dev stack unrenderable and "the syntax looks right" is not the same as "the targets are
# distinct";
# 5. the service-role partition, because a service the lane renders and files under no role is
# started by nothing and checked by nothing, and a one-shot filed as a --wait target hangs the
# lane for its full timeout on a container that was built to exit;
# 6. the expected application report (expectedCapabilitiesOn, expectedPersistenceVendor) names
# only catalogued capabilities and a vendor that agrees with persistence-jpa, because an
# expectation the application cannot report fails every run of the lane;
# 7. a lane that switches Redis on authenticates as an account its Redis provisions, because the
# 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/app-bootstrap/compose-lanes/compose-profile-contracts.json"
FAILURES=0
fail() { echo " FAIL: $*" >&2; FAILURES=$((FAILURES + 1)); }
# Prints one line for each way a Redis lane falls short of authenticating as an account its own
# Redis provisions; prints nothing when it does not. $1 is the lane, $2 its rendered model.
#
# Read against the rendered model rather than the source files, so the ACL file checked is the one
# the container actually mounts. The account line is compared with what the lane supplies — user,
# password and key pattern — because each of the three fails differently and only at runtime: an
# unknown user or a wrong password is WRONGPASS at the first connection, and a key pattern that
# does not cover the lane's namespace is NOPERM on the first key a capability writes, long after
# startup reported healthy.
CREDENTIAL_REFERENCE_FORM='^secret://([A-Za-z0-9_.-]+)@environment/([A-Za-z_][A-Za-z0-9_]*)$'
redis_authentication_problems() {
local lane="$1" model="$2"
local env namespace
env="$(jq -c '.activationEnv // {}' <<<"${lane}")"
if [[ "$(jq -r '.APP_REDIS_AUTHENTICATION_ANONYMOUS_ACCESS_ACCEPTED // empty' <<<"${env}")" == "true" ]]; then
echo "accepts anonymous Redis access; the lane's Redis turns the default user off, so the application has to name an account"
fi
namespace="$(jq -r '.APP_REDIS_NAMESPACE_ENVIRONMENT // empty' <<<"${env}")"
[[ -n "${namespace}" ]] \
|| echo "sets no APP_REDIS_NAMESPACE_ENVIRONMENT, so nothing says the account's key pattern covers the keys the lane writes"
local acl_path acl_file acl_label
acl_path="$(jq -r '.services.redis.command // [] | . as $c | (index("--aclfile") // empty) as $i | $c[$i + 1] // empty' <<<"${model}")"
if [[ -z "${acl_path}" ]]; then
echo "starts Redis without --aclfile, so the default user is open and nothing authenticates"
return 0
fi
acl_file="$(jq -r --arg p "${acl_path}" '
[.services.redis.volumes // [] | .[] | select(.type == "bind" and .read_only == true)
| . as $v | select($p | startswith($v.target + "/")) | $v.source + ($p | ltrimstr($v.target))]
| first // empty' <<<"${model}")"
if [[ -z "${acl_file}" || ! -r "${acl_file}" ]]; then
echo "starts Redis with --aclfile ${acl_path}, which no read-only bind mount of a repository file provides"
return 0
fi
acl_label="${acl_file#"${REPO_ROOT}/"}"
grep -qx 'user default off' "${acl_file}" \
|| echo "${acl_label} leaves the default user on, which makes every account restriction optional"
[[ "$(jq -r '.services.redis.healthcheck.test // [] | join(" ")' <<<"${model}")" == *"--user "* ]] \
|| echo "the Redis healthcheck does not authenticate as a named account, so it cannot pass with the default user off"
local setting reference user name value account
for setting in APP_REDIS_AUTHENTICATION_CREDENTIAL_REFERENCE APP_REDIS_AUTHENTICATION_ADVANCED_CREDENTIAL_REFERENCE; do
reference="$(jq -r --arg k "${setting}" '.[$k] // empty' <<<"${env}")"
if [[ ! "${reference}" =~ ${CREDENTIAL_REFERENCE_FORM} ]]; then
echo "${setting} is '${reference}', not secret://<account>@environment/<variable>"
continue
fi
user="${BASH_REMATCH[1]}"
name="${BASH_REMATCH[2]}"
value="$(jq -r --arg k "${name}" '.[$k] // empty' <<<"${env}")"
if [[ -z "${value}" ]]; then
echo "${setting} reads ${name}, which the lane does not supply"
continue
fi
account="$(grep -E "^user ${user} on( |$)" "${acl_file}" || true)"
if [[ -z "${account}" ]]; then
echo "${setting} names ${user}, which ${acl_label} does not enable"
continue
fi
[[ " ${account} " == *" >${value} "* ]] \
|| echo "${name} is not the password ${acl_label} gives ${user}"
[[ -z "${namespace}" || " ${account} " == *" ~${namespace}:* "* ]] \
|| echo "${user} may not touch ${namespace}:*, the namespace this lane writes"
done
}
command -v jq >/dev/null 2>&1 || { echo "jq is required" >&2; exit 78; }
command -v docker >/dev/null 2>&1 || { echo "docker is required" >&2; exit 78; }
[[ -r "${CONTRACTS}" ]] || { echo "missing ${CONTRACTS}" >&2; exit 78; }
# ---- 1. Compose version floor ------------------------------------------------
REQUIRED="$(jq -r '.minimumComposeVersion' "${CONTRACTS}")"
ACTUAL="$(docker compose version --short | sed 's/^v//')"
if [[ "$(printf '%s\n%s\n' "${REQUIRED}" "${ACTUAL}" | sort -V | head -1)" != "${REQUIRED}" ]]; then
echo "docker compose ${ACTUAL} is below the required ${REQUIRED};" >&2
echo " the dev overlay needs !override to replace the base tmpfs rather than merge with it." >&2
exit 1
fi
echo "compose version ${ACTUAL} >= ${REQUIRED}"
# ---- per-lane checks ---------------------------------------------------------
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}")"
runtime="$(jq -r '.springRuntime' <<<"${lane}")"
expected="$(jq -r '.services | sort | join(",")' <<<"${lane}")"
args=()
while read -r key; do
file="$(jq -r --arg k "${key}" '.composeFiles[$k]' "${CONTRACTS}")"
[[ -r "${REPO_ROOT}/${file}" ]] || { fail "${id}: ${file} is missing"; continue 2; }
args+=(-f "${REPO_ROOT}/${file}")
done < <(jq -r '.files[]' <<<"${lane}")
profile_args=()
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
# own warning about an unset interpolation variable arrived as an extra "service" and twelve lanes
# failed with a timestamped log line in place of a container name.
render_error="${TMPDIR:-/tmp}/compose-config-$$.err"
if ! actual="$(cd "${REPO_ROOT}" && docker compose "${args[@]}" "${profile_args[@]}" config --services 2>"${render_error}" | sort | paste -sd, -)"; then
fail "${id}: the stack does not render: $(tr '\n' ' ' <"${render_error}")"
rm -f "${render_error}"
continue
fi
rm -f "${render_error}"
if [[ "${actual}" != "${expected}" ]]; then
fail "${id}: services are [${actual}], the contract says [${expected}]"
continue
fi
# 3. the rendered Spring runtime, and 4. mount-target uniqueness
model="$(cd "${REPO_ROOT}" && docker compose "${args[@]}" "${profile_args[@]}" config --format json 2>/dev/null)" || {
fail "${id}: the merged model does not render as JSON"
continue
}
rendered_runtime="$(jq -r '.services.app.environment.SPRING_PROFILES_ACTIVE // empty' <<<"${model}")"
if [[ "${rendered_runtime}" != "${runtime}" ]]; then
fail "${id}: app renders SPRING_PROFILES_ACTIVE='${rendered_runtime}', the contract says '${runtime}'"
fi
duplicates="$(jq -r '
.services | to_entries[]
| .key as $svc
| [ (.value.volumes // [] | .[].target), (.value.tmpfs // [] | .[] | split(":")[0]) ] as $targets
| ($targets | group_by(.) | map(select(length > 1) | .[0])) as $dupes
| select($dupes | length > 0)
| "\($svc): \($dupes | join(", "))"' <<<"${model}")"
if [[ -n "${duplicates}" ]]; then
fail "${id}: a mount target is declared twice — ${duplicates}"
fi
# 5. every rendered service plays exactly one role, and no non-waiting service is a --wait target.
#
# The wrapper runs longRunningServices under `up --wait`, preStartServices with `run --rm` before
# the application, and oneShotServices with `run --rm` after it is healthy. A service the lane
# renders but files under none of the three is started by nothing and checked by nothing, and one
# filed under two is run twice. Neither is visible in a green lane.
#
# The direction that actually bites is a one-shot reaching longRunningServices: `up --wait` on a
# container built to exit waits for a health state it will never report, and the lane hangs until
# the 300s timeout with no indication that the contract, not the stack, is what is wrong.
partition="$(jq -r '
( (.longRunningServices // []) + (.preStartServices // []) + (.oneShotServices // []) ) as $filed
| { missing: ((.services // []) - $filed), extra: ($filed - (.services // [])),
twice: ($filed | group_by(.) | map(select(length > 1) | .[0])) }
| select((.missing | length) + (.extra | length) + (.twice | length) > 0)
| "unfiled=[\(.missing | join(","))] not-rendered=[\(.extra | join(","))] twice=[\(.twice | join(","))]"
' <<<"${lane}")"
[[ -n "${partition}" ]] && fail "${id}: services are not partitioned by role — ${partition}"
never_waiting="$(jq -r --argjson lane "${lane}" '
( (.preStartServices // []) + (.oneShotServices // []) ) as $catalogue
| ( ($lane.longRunningServices // []) - (($lane.longRunningServices // []) - $catalogue) )
| select(length > 0) | join(",")' "${CONTRACTS}")"
[[ -n "${never_waiting}" ]] && fail "${id}: [${never_waiting}] are declared non-waiting but listed as --wait targets"
uncatalogued="$(jq -r --argjson lane "${lane}" '
( (.preStartServices // []) + (.oneShotServices // []) ) as $catalogue
| ( (($lane.preStartServices // []) + ($lane.oneShotServices // [])) - $catalogue )
| select(length > 0) | join(",")' "${CONTRACTS}")"
[[ -n "${uncatalogued}" ]] && fail "${id}: [${uncatalogued}] are run with \`run --rm\` but are in neither top-level catalogue"
# 6. what the lane expects the application to report is something it can report. The wrapper
# compares expectedCapabilitiesOn with the names under info.capabilities whose enabled is true, and
# the whole reported set with the top-level `capabilities` catalogue; a name outside the catalogue
# can never match. The vendor is reported only while persistence-jpa is on, so a vendor expected
# with JPA off, or none expected with it on, is a contract that fails every run.
expectation="$(jq -r --argjson lane "${lane}" '
( ($lane.expectedCapabilitiesOn // []) - (.capabilities // []) ) as $unknown
| ( ($lane.expectedCapabilitiesOn // []) | index("persistence-jpa") != null ) as $jpa
| [ (if ($unknown | length) > 0 then "uncatalogued=[\($unknown | join(","))]" else empty end),
(if $jpa == ($lane.expectedPersistenceVendor == "none")
then "vendor \($lane.expectedPersistenceVendor) with persistence-jpa \(if $jpa then "on" else "off" end)"
else empty end) ]
| join(" ")' "${CONTRACTS}")"
[[ -n "${expectation}" ]] && fail "${id}: the expected application report is unreachable — ${expectation}"
# 7. a lane that switches Redis on authenticates as an account its Redis provisions.
if [[ "$(jq -r '.activationEnv.APP_REDIS_ENABLED // empty' <<<"${lane}")" == "true" ]]; then
while read -r problem; do
[[ -n "${problem}" ]] && fail "${id}: ${problem}"
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
# 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 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 "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
fail "the Keycloak realm carries key(s) Keycloak refuses to deserialize: ${annotations}"
fi
fi
fi
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/app-bootstrap/compose-lanes/compose-profile-contracts.json"