#!/usr/bin/env bash # The static half of the Compose contract: every lane renders, and renders exactly what it claims. # # Called by: the pull-request stage `prCheck` (`verifyComposeProfiles`, root build.gradle) and # scripts/run-compose-runtime-smoke.sh before it starts the lanes. # # Ten 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 application's heap dump path (-XX:HeapDumpPath in the Dockerfile) is not a tmpfs, because a # tmpfs is charged to the container's memory limit and is gone once the container exits: the # dump written at an OutOfMemoryError could only push the container into an OOM kill and was # never there to read (2026-11-12 review). # 10. 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/bootstrap/app/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://@environment/" 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; } HEAP_DUMP_PATH="$(sed -n 's/.*-XX:HeapDumpPath=\([^ \\"]*\).*/\1/p' "${REPO_ROOT}/Dockerfile" | head -1)" [[ -n "${HEAP_DUMP_PATH}" ]] || { echo "the Dockerfile sets no -XX:HeapDumpPath" >&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 # 9. the heap dump path is not a tmpfs. heap_tmpfs="$(jq -r --arg path "${HEAP_DUMP_PATH}" \ '.services.app.tmpfs // [] | .[] | split(":")[0] | select(. == $path)' <<<"${model}")" if [[ -n "${heap_tmpfs}" ]]; then fail "${id}: app mounts the heap dump path ${HEAP_DUMP_PATH} as a tmpfs, which counts against its memory limit and is gone when it exits" fi [[ ${FAILURES} -eq 0 ]] && echo "${id}: ${expected} @ ${runtime}" done # 10. 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/bootstrap/app/compose-lanes/compose-profile-contracts.json"