Files
clean-architecture-backend-…/scripts/verify-compose-profile-contracts.sh
T
DongHyeonka 5786126cfa fix!: 남은 리뷰 항목과 합친 뒤 드러난 결함을 고친다
문제: 앞 커밋 뒤에도 알림·파일 서버 묶음이 합쳐지지 않았고, 포트 다수에
fake와 실제 구현이 함께 통과하는 공유 계약이 없었고, SpotBugs가 신뢰도
HIGH만 봤고, application-core에 관계없는 클래스 묶음 패키지(outbound)가
있었다. 묶음을 합치자 lane·검사가 새로 드러낸 결함도 있었다(JpaOutbox
Store가 읽기 전용 트랜잭션에서 이벤트를 조용히 잃음, gRPC admission
controller가 public synchronized라 외부 lock에 막힘, 소비자 decode 타입
등록 경로 없음, compose Redis 익명 접근, local-fileserver lane DB 없음).

방법: 리뷰 README 15절에 남은 결정을 모두 적고 그대로 고쳤다. 트랜잭션·
멱등성·발행·notification 포트에 testFixtures 계약 키트를 두고 fake와
PG·Redis 구현이 상속한다(fake 변이로 계약이 잡는지 확인). SpotBugs는
MEDIUM으로 내리고 진짜 결함은 고치고 오탐은 위치·패턴별 이유를 단
제외로 처리했다. 업무 기능 패키지 규칙을 application-core/CLAUDE.md에
정본으로 두고 ArchUnit 2개와 생성 명령이 강제한다. compose Redis는
infra/redis-sdk ACL로 뜬다. 묶음별 결과는 리뷰 README 16절에 있다.

위험·한계: APP_FLYWAY_ENABLED가 dev·prod에도 적용된다. app.security
오타 키가 이제 기동을 막는다. SES 콜백 replay 창 기본값이 1시간이다.
템플릿 패키지 목록은 CLAUDE.md 표와 TemplatePackageOwnership 두 곳에
있고 일치 검사는 없다. 실제 CI runner 실행은 확인하지 못했다.

검증: ci, mainCheck, integrationCheck, -p optional-platforms ci
integrationCheck, performanceCheck, releaseCheck(-PgitRevision),
verify-compose-profile-contracts(18 lane) 통과. compose lane 실제 기동:
local-fileserver, notification ingest·serving·handoff, local-redis,
all-adapters(smoke 3개 포함).

Refs: docs/reviews/2026-11-01-maturity-review/README.md 15·16절
BREAKING CHANGE: APP_FLYWAY_ENABLED가 dev·prod 프로필에도 적용되고,
app.security의 모르는 키는 기동을 거부한다. MessageHandler에
schemaVersions()가 생겨 decode 목록을 handler 선언에서 만든다.
2026-11-03 19:52:06 +09:00

253 lines
14 KiB
Bash
Executable File

#!/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:
#
# 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.
#
# 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"
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}")"
profile="$(jq -r '.composeProfile // empty' <<<"${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=()
[[ -n "${profile}" ]] && profile_args=(--profile "${profile}")
# 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
[[ ${FAILURES} -eq 0 ]] && echo "${id}: ${expected} @ ${runtime}"
done
# 8. 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"
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"
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/config/runtime/compose-profile-contracts.json"