From 474bd0462c937f2faf0f0a0f5d30e812100f9c6b Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sun, 22 Nov 2026 00:37:57 +0900 Subject: [PATCH] =?UTF-8?q?fix(compose):=20=EA=B3=84=EC=95=BD=20=EA=B2=80?= =?UTF-8?q?=EC=82=AC=EC=9D=98=20=ED=8C=90=EC=A0=95=EC=9D=84=20=EC=8B=9C?= =?UTF-8?q?=ED=97=98=20=EC=9E=88=EB=8A=94=20=EC=8A=A4=ED=81=AC=EB=A6=BD?= =?UTF-8?q?=ED=8A=B8=EB=A1=9C=20=EC=98=AE=EA=B8=B0=EA=B3=A0=20=EB=B9=88=20?= =?UTF-8?q?=EC=9E=85=EB=A0=A5=20=ED=86=B5=EA=B3=BC=EB=A5=BC=20=EB=A7=89?= =?UTF-8?q?=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit scripts/verify-compose-profile-contracts.sh는 prCheck의 게이트인데 판정 열 가지가 셸 안의 jq라 시험이 없다. 고장 난 입력을 넣어 보면 넷이 통과한다. - 계약의 lanes가 비면 lane 반복이 돌지 않고 "all 0 lanes match"로 끝난다. - persistence-jpa를 켠 lane에 expectedPersistenceVendor가 없으면 통과한다. smoke는 보고된 vendor를 그 칸과 비교하니 그 lane은 매번 실패한다. - heap dump 경로는 짧은 `tmpfs:` 목록의 같은 항목만 비교한다. 위 디렉터리의 tmpfs(/var/tmp)나 long syntax `type: tmpfs` volume은 통과한다. - Redis 계정을 이름 그대로가 아니라 정규식으로 찾아 `.`이 아무 글자와 맞는다. `ca.skeleton-application`을 가리키는 lane이 `ca-skeleton-application` 줄로 통과한다. 판정을 scripts/compose-contract-verdict.py로 옮긴다. 셸은 docker만 부른다. `version`으로 Compose 하한을 먼저 보고, `lanes`가 준 lane별 인자로 `config --services`와 `config --format json`을 돌려 출력과 rc를 파일에 쓴다. rc는 조건 밖에서 읽는다. 그다음 `judge`가 그 디렉터리를 읽는다. 판정은 위 넷을 실패로 보고, 파일 없는 lane, 겹치는 id, smoke가 읽는 목록이 없거나 그 목록에 이름이 아닌 원소가 든 lane, 셸이 렌더 기록을 남기지 않은 lane도 실패로 본다. docker 호출의 stdin은 /dev/null이라 lane 목록을 먹지 않는다. scripts/tests/test_compose_contract_verdict.py가 판정마다 고장 난 입력과 정상 입력을 보고, 셸을 가짜 docker로 돌려 lane 인자·rc 기록·판정 rc를 본다. prCheck의 testDocumentChecks가 돌린다. 루트 build.gradle의 주석은 PR 단계 Exec 태스크마다 시험 파일을 적어 사실과 맞춘다. 버린 안: 모델 JSON의 service key로 `config --services`를 대신하기. 렌더를 한 번 줄이지만 지금 lane 결과와 같은지 따로 보여야 해서 두 호출을 그대로 둔다. bats는 desktop과 runner 둘 다에 새 도구를 깔아야 한다. 위험·한계: 판정이 jq와 다른 곳은 위 넷 말고도 있다. main이 통과시키고 이제 실패로 보는 것: 같은 사용자를 두 줄에서 켠 ACL(Redis가 거절한다), 값이 null·false인 realm의 `_` key, 최상위 값이 둘인 realm, LANE_ID 꼴이 아닌 id, 빈 springRuntime, `files`가 없는 lane, 이름이 아닌 목록 원소, 읽을 수 없는 Compose 버전. main이 실패시키고 이제 통과하는 것: ACL 줄의 겹친 공백과 CRLF, 끝에 `/`가 붙은 bind target, 로캘에 따라 달라지던 service 정렬, list 꼴 environment, 파일 하나로 bind mount한 ACL(target이 --aclfile 경로와 같음). Redis가 ACL 줄의 `\r`와 겹친 공백을 받아들인다는 것은 acl.c를 열어 보지 않은 판단이다. 실제 계약 18 lane에서는 main과 이 트리의 출력 줄이 같다(PR 본문). 검증: 노트북 `python3 -m unittest discover -s scripts/tests` 275개 통과. 판정의 빈 lane 거절·vendor 검사·heap 상위 tmpfs·long syntax tmpfs·비밀번호 글자 비교· 정확한 service 집합·사용자 이름 비교·렌더 기록 없음·파일 없는 lane·목록 원소 검사를 되돌리거나, judge_lane에서 판정 하나를 빼거나 realm 판정을 빼거나, 셸의 두 렌더 rc를 `|| true`로 삼키거나, docker가 stdin을 읽게 두거나, judge 호출을 지우거나 `|| true`로 바꾸거나, version 실패를 무시하거나, profile 인자를 빼면 새 시험이 실패한다(변이 23개 모두). desktop RED·GREEN과 prCheck 결과는 PR 본문에 있다. Refs: REV-BE-0016 --- build.gradle | 7 +- scripts/compose-contract-verdict.py | 572 ++++++++++++ .../tests/test_compose_contract_verdict.py | 829 ++++++++++++++++++ scripts/verify-compose-profile-contracts.sh | 278 +----- 4 files changed, 1449 insertions(+), 237 deletions(-) create mode 100644 scripts/compose-contract-verdict.py create mode 100644 scripts/tests/test_compose_contract_verdict.py diff --git a/build.gradle b/build.gradle index 4ed0ece2..3cc5b2e2 100644 --- a/build.gradle +++ b/build.gradle @@ -202,8 +202,11 @@ tasks.register('mainCheck') { dependsOn tasks.named('verifyFeatureScaffold') } -// The checks outside Gradle that the pull-request stage runs. Each is a script with its own tests -// (scripts/tests); these tasks only give them a stage, so pr.yml and scripts/verify.sh run the same +// The checks outside Gradle that the pull-request stage runs. Each has its tests in scripts/tests, +// which testDocumentChecks runs: verifyComposeProfiles in test_compose_contract_verdict.py (its shell +// keeps the docker calls, scripts/compose-contract-verdict.py the judgements), verifyRepositoryLayout +// in test_check_repo_layout.py, verifyWorkDocs in test_check_work_docs.py, documentCheck in +// test_check_docs.py. These tasks only give them a stage, so pr.yml and scripts/verify.sh run the same // one line. Repository root as working directory: that is where the scripts expect to start. def repositoryRoot = rootProject.projectDir tasks.register('verifyComposeProfiles', Exec) { diff --git a/scripts/compose-contract-verdict.py b/scripts/compose-contract-verdict.py new file mode 100644 index 00000000..6262b7ca --- /dev/null +++ b/scripts/compose-contract-verdict.py @@ -0,0 +1,572 @@ +"""Judges the static Compose contract: every lane renders, and renders exactly what it claims. + +Called by scripts/verify-compose-profile-contracts.sh, which keeps the docker calls: it asks this +script which lanes to render and with which arguments, writes what `docker compose config` printed and +exited with to one directory, and hands that directory back here. The judgements live here rather +than in jq inside the shell because a jq branch cannot be tried on a broken input without Docker, and +four of them passed input that should have failed them (scripts/tests has the cases): + +- a contract with no lanes passed as "all 0 lanes match"; +- a lane that turns persistence-jpa on and names no expectedPersistenceVendor passed, although the + smoke wrapper compares the reported vendor with that field and fails every run of the lane; +- the heap dump path passed when the tmpfs was a directory above it, or a long-syntax volume of + type tmpfs, because only an exact entry of the short `tmpfs:` list was compared; +- a Redis account was looked up with its name as a regular expression, so a lane that names + `ca.skeleton-application` passed on the ACL line of `ca-skeleton-application`, an account it never + authenticates as. + +The ten checks, and why each exists, are listed in scripts/verify-compose-profile-contracts.sh. + +Exit status 0 is a pass, 1 a failure with its reasons on stderr, 2 a call this script does not know, +78 a repository this script cannot read (no contract file, no -XX:HeapDumpPath in the Dockerfile). + + python3 scripts/compose-contract-verdict.py version + python3 scripts/compose-contract-verdict.py lanes + python3 scripts/compose-contract-verdict.py judge + +`lanes` prints one line per lane the contract lets it render: the lane id, then the arguments for +`docker compose`, separated by tabs. `judge` expects, for each of those lanes, `.services` and +`.services.err` from `config --services`, `.json` from `config --format json`, and the exit +status of each call in `.services.rc` and `.json.rc`. A lane the contract describes but the +shell left no record for fails, so a broken loop in the shell cannot pass as a lane that matched. +""" + +from __future__ import annotations + +import argparse +import json +import os +import posixpath +import re +import shlex +import sys +from dataclasses import dataclass +from pathlib import Path + +DEFAULT_REPO_ROOT = Path(__file__).resolve().parent.parent +CONTRACT_LABEL = "src/bootstrap/app/compose-lanes/compose-profile-contracts.json" +REALM = "compose/keycloak/realms/ca-skeleton-realm.json" +HEAP_DUMP_PATH = re.compile(r'-XX:HeapDumpPath=([^ \\"]*)') +LANE_ID = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]*") +VERSION = re.compile(r"v?(\d+(?:\.\d+)*)(?:[-+].*)?") +MEMORY_SIZE = re.compile(r"[1-9][0-9]*[kmg]") +CREDENTIAL_REFERENCE = re.compile(r"secret://([A-Za-z0-9_.-]+)@environment/([A-Za-z_][A-Za-z0-9_]*)") +REDIS_REFERENCES = ( + "APP_REDIS_AUTHENTICATION_CREDENTIAL_REFERENCE", + "APP_REDIS_AUTHENTICATION_ADVANCED_CREDENTIAL_REFERENCE", +) +SETUP = 78 + + +class SetupError(Exception): + """The repository lacks something every judgement needs; exit 78 rather than judge.""" + + +@dataclass(frozen=True) +class Rendered: + """What the shell recorded for one lane. None is a file the shell never wrote.""" + + services_rc: int | None + services: str + services_error: str + model_rc: int | None + model: str + + +def scalar(value: object) -> str: + """The value as `jq -r '... // empty'` prints it: null and false print nothing.""" + if value is None or value is False: + return "" + if value is True: + return "true" + return str(value) + + +def strings(value: object) -> list[str]: + """A list of strings, or an empty list for anything else (`// []`).""" + if isinstance(value, list): + return [item for item in value if isinstance(item, str)] + return [] + + +# ---- 1. Compose version floor ---------------------------------------------------------------- + +def version_key(text: str) -> tuple[int, ...] | None: + match = VERSION.fullmatch(text.strip()) + if match is None: + return None + return tuple(int(part) for part in match.group(1).split(".")) + + +def compose_version(contract: dict, actual: str) -> list[str]: + """The reasons this Compose is too old for the contract; empty when it is new enough.""" + required = scalar(contract.get("minimumComposeVersion")) + floor, found = version_key(required), version_key(actual) + if floor is None: + return [f"minimumComposeVersion '{required}' is not a version such as 2.24.4"] + if found is None: + return [f"docker compose reports '{actual.strip()}', which is not a version"] + width = max(len(floor), len(found)) + if found + (0,) * (width - len(found)) < floor + (0,) * (width - len(floor)): + return [ + f"docker compose {actual.strip()} is below the required {required};", + " the dev overlay needs !override to replace the base tmpfs rather than merge with it.", + ] + return [] + + +# ---- the shape of the contract ---------------------------------------------------------------- + +def lane_shape(contract: dict, lane: object, repo_root: Path) -> list[str]: + """The reasons a lane cannot be rendered or run as the contract writes it; empty when it can.""" + if not isinstance(lane, dict): + return ["the lane is not an object"] + problems: list[str] = [] + files = lane.get("files") + catalogue = contract.get("composeFiles") if isinstance(contract.get("composeFiles"), dict) else {} + if not isinstance(files, list) or not files: + problems.append("names no compose file under 'files', so `docker compose` would render whatever " + "file it finds in the repository root") + else: + for key in files: + path = catalogue.get(key) if isinstance(key, str) else None + if not isinstance(path, str): + problems.append(f"names compose file '{key}', which composeFiles does not list") + elif not (repo_root / path).is_file(): + problems.append(f"{path} is missing") + for field in ("composeProfiles", "expectedCapabilitiesOn"): + if not isinstance(lane.get(field), list): + problems.append(f"has no '{field}' list; the smoke wrapper reads it as one") + # The checks below read these lists as names. An entry that is not one (null, a number, "") would + # drop out of them unseen, while the smoke wrapper reads every entry and fails the lane on it. + for field in ("composeProfiles", "expectedCapabilitiesOn", "services", "longRunningServices", + "preStartServices", "oneShotServices"): + entries = lane.get(field) + if isinstance(entries, list) and not all(isinstance(entry, str) and entry for entry in entries): + problems.append(f"'{field}' holds {json.dumps(entries)}, and every entry must be a name") + if not isinstance(lane.get("springRuntime"), str) or not lane["springRuntime"]: + problems.append("names no springRuntime") + if not isinstance(lane.get("services"), list) or not lane["services"]: + problems.append("lists no services") + return problems + + +def lanes(contract: dict, repo_root: Path) -> tuple[list[dict], list[str]]: + """The lanes that can be rendered, and the reasons the others cannot (each with its lane id).""" + entries = contract.get("lanes") + if not isinstance(entries, list) or not entries: + return [], ["the contract declares no lanes, so nothing would be checked"] + renderable: list[dict] = [] + problems: list[str] = [] + seen: set[str] = set() + for index, lane in enumerate(entries): + lane_id = lane.get("id") if isinstance(lane, dict) else None + if not isinstance(lane_id, str) or LANE_ID.fullmatch(lane_id) is None: + problems.append(f"lane {index}: id {lane_id!r} is not a name such as off-local") + continue + if lane_id in seen: + problems.append(f"{lane_id}: the id is used by more than one lane") + continue + seen.add(lane_id) + shape = lane_shape(contract, lane, repo_root) + if shape: + problems.extend(f"{lane_id}: {problem}" for problem in shape) + continue + renderable.append(lane) + return renderable, problems + + +def compose_arguments(contract: dict, lane: dict, repo_root: Path) -> list[str]: + arguments: list[str] = [] + for key in lane["files"]: + arguments += ["-f", str(repo_root / contract["composeFiles"][key])] + for profile in strings(lane["composeProfiles"]): + if profile: + arguments += ["--profile", profile] + return arguments + + +# ---- per-lane checks -------------------------------------------------------------------------- + +def service_set(lane: dict, rendered: str) -> list[str]: + """2. The stack renders exactly the lane's services: not a superset, not a subset.""" + expected = sorted(strings(lane.get("services"))) + actual = sorted(line.strip() for line in rendered.splitlines() if line.strip()) + if actual != expected: + return [f"services are [{','.join(actual)}], the contract says [{','.join(expected)}]"] + return [] + + +def environment(service: dict) -> dict[str, object]: + value = service.get("environment") + if isinstance(value, dict): + return value + if isinstance(value, list): + return dict(item.split("=", 1) if "=" in item else (item, None) for item in strings(value)) + return {} + + +def spring_runtime(lane: dict, model: dict) -> list[str]: + """3. The application renders the Spring runtime the lane names.""" + app = model.get("services", {}).get("app") or {} + rendered = scalar(environment(app).get("SPRING_PROFILES_ACTIVE")) + if rendered != lane["springRuntime"]: + return [f"app renders SPRING_PROFILES_ACTIVE='{rendered}', the contract says '{lane['springRuntime']}'"] + return [] + + +def tmpfs_targets(service: dict) -> list[str]: + """Every tmpfs the service mounts: the short `tmpfs:` list and long-syntax volumes of type tmpfs.""" + short = service.get("tmpfs") + entries = [short] if isinstance(short, str) else strings(short) + targets = [entry.split(":")[0] for entry in entries] + targets += [volume["target"] for volume in mounts(service) if volume.get("type") == "tmpfs"] + return targets + + +def mounts(service: dict) -> list[dict]: + volumes = service.get("volumes") + if not isinstance(volumes, list): + return [] + return [volume for volume in volumes if isinstance(volume, dict) and isinstance(volume.get("target"), str)] + + +def duplicate_mounts(model: dict) -> list[str]: + """4. No service declares the same mount target twice.""" + problems: list[str] = [] + for name, service in (model.get("services") or {}).items(): + if not isinstance(service, dict): + continue + short = service.get("tmpfs") + entries = [short] if isinstance(short, str) else strings(short) + targets = [volume["target"] for volume in mounts(service)] + [entry.split(":")[0] for entry in entries] + twice = sorted({target for target in targets if targets.count(target) > 1}) + if twice: + problems.append(f"a mount target is declared twice — {name}: {', '.join(twice)}") + return problems + + +def role_partition(contract: dict, lane: dict) -> list[str]: + """5. Every rendered service plays exactly one role, and no one-shot is a --wait target.""" + problems: list[str] = [] + services = strings(lane.get("services")) + waiting = strings(lane.get("longRunningServices")) + pre_start = strings(lane.get("preStartServices")) + one_shot = strings(lane.get("oneShotServices")) + filed = waiting + pre_start + one_shot + unfiled = [service for service in services if service not in filed] + not_rendered = [service for service in filed if service not in services] + twice = sorted({service for service in filed if filed.count(service) > 1}) + if unfiled or not_rendered or twice: + problems.append( + f"services are not partitioned by role — unfiled=[{','.join(unfiled)}] " + f"not-rendered=[{','.join(not_rendered)}] twice=[{','.join(twice)}]" + ) + catalogue = strings(contract.get("preStartServices")) + strings(contract.get("oneShotServices")) + never_waiting = [service for service in waiting if service in catalogue] + if never_waiting: + problems.append(f"[{','.join(never_waiting)}] are declared non-waiting but listed as --wait targets") + uncatalogued = [service for service in pre_start + one_shot if service not in catalogue] + if uncatalogued: + problems.append( + f"[{','.join(uncatalogued)}] are run with `run --rm` but are in neither top-level catalogue" + ) + return problems + + +def application_report(contract: dict, lane: dict) -> list[str]: + """6. What the lane expects /actuator/info to report is something the application can report.""" + expected_on = strings(lane.get("expectedCapabilitiesOn")) + unknown = [name for name in expected_on if name not in strings(contract.get("capabilities"))] + jpa = "persistence-jpa" in expected_on + state = "on" if jpa else "off" + vendor = lane.get("expectedPersistenceVendor") + reasons: list[str] = [] + if unknown: + reasons.append(f"uncatalogued=[{','.join(unknown)}]") + if not isinstance(vendor, str) or not vendor: + reasons.append(f"no expectedPersistenceVendor with persistence-jpa {state}") + elif jpa == (vendor == "none"): + reasons.append(f"vendor {vendor} with persistence-jpa {state}") + if reasons: + return [f"the expected application report is unreachable — {' '.join(reasons)}"] + return [] + + +def redis_authentication(lane: dict, model: dict, repo_root: Path) -> list[str]: + """7. A lane that switches Redis on authenticates as an account its own Redis provisions. + + Read against the rendered model, so the ACL file checked is the one the container mounts. User, + password and key pattern are each compared, because each 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. + """ + env = lane.get("activationEnv") if isinstance(lane.get("activationEnv"), dict) else {} + if scalar(env.get("APP_REDIS_ENABLED")) != "true": + return [] + problems: list[str] = [] + if scalar(env.get("APP_REDIS_AUTHENTICATION_ANONYMOUS_ACCESS_ACCEPTED")) == "true": + problems.append("accepts anonymous Redis access; the lane's Redis turns the default user off, " + "so the application has to name an account") + namespace = scalar(env.get("APP_REDIS_NAMESPACE_ENVIRONMENT")) + if not namespace: + problems.append("sets no APP_REDIS_NAMESPACE_ENVIRONMENT, so nothing says the account's key " + "pattern covers the keys the lane writes") + + redis = model.get("services", {}).get("redis") or {} + command = redis.get("command") + words = shlex.split(command) if isinstance(command, str) else strings(command) + position = words.index("--aclfile") if "--aclfile" in words else None + acl_path = words[position + 1] if position is not None and position + 1 < len(words) else "" + if not acl_path: + problems.append("starts Redis without --aclfile, so the default user is open and nothing authenticates") + return problems + acl_file = acl_source(redis, acl_path) + if acl_file is None or not acl_file.is_file() or not os.access(acl_file, os.R_OK): + problems.append(f"starts Redis with --aclfile {acl_path}, which no read-only bind mount of a " + "repository file provides") + return problems + label = relative(acl_file, repo_root) + acl_lines = acl_file.read_text(encoding="utf-8", errors="replace").splitlines() + if "user default off" not in acl_lines: + problems.append(f"{label} leaves the default user on, which makes every account restriction optional") + test = (redis.get("healthcheck") or {}).get("test") + probe = test if isinstance(test, str) else " ".join(strings(test)) + if "--user " not in probe: + problems.append("the Redis healthcheck does not authenticate as a named account, so it cannot " + "pass with the default user off") + + for setting in REDIS_REFERENCES: + reference = scalar(env.get(setting)) + match = CREDENTIAL_REFERENCE.fullmatch(reference) + if match is None: + problems.append(f"{setting} is '{reference}', not secret://@environment/") + continue + user, name = match.group(1), match.group(2) + value = scalar(env.get(name)) + if not value: + problems.append(f"{setting} reads {name}, which the lane does not supply") + continue + # Whole words, not patterns: the account is the line whose second word is the user name, so + # '.' in it is a dot, and the password is the exact word after '>'. + accounts = [line.split() for line in acl_lines if line.split()[:3] == ["user", user, "on"]] + if not accounts: + problems.append(f"{setting} names {user}, which {label} does not enable") + continue + if len(accounts) > 1: + problems.append(f"{label} enables {user} on more than one line, which Redis refuses to load") + continue + if f">{value}" not in accounts[0]: + problems.append(f"{name} is not the password {label} gives {user}") + if namespace and f"~{namespace}:*" not in accounts[0]: + problems.append(f"{user} may not touch {namespace}:*, the namespace this lane writes") + return problems + + +def acl_source(redis: dict, acl_path: str) -> Path | None: + """The repository file a read-only bind mount puts at acl_path, if one does.""" + for volume in mounts(redis): + if volume.get("type") != "bind" or volume.get("read_only") is not True: + continue + target, source = volume["target"], volume.get("source") + if not isinstance(source, str): + continue + if acl_path == target: + return Path(source) + if acl_path.startswith(target.rstrip("/") + "/"): + return Path(source + acl_path[len(target.rstrip("/")):]) + return None + + +def memory_limit(lane: dict) -> list[str]: + """8. The lane's own memory limit, when it sets one, is a Compose memory size.""" + limit = scalar(lane.get("appMemoryLimit")) + if limit and MEMORY_SIZE.fullmatch(limit) is None: + return [f"appMemoryLimit '{limit}' is not a Compose memory size such as 1g"] + return [] + + +def heap_dump(model: dict, heap_path: str) -> list[str]: + """9. The heap dump path is on no tmpfs: not one at that path, and not one at a directory above it.""" + app = model.get("services", {}).get("app") or {} + path = posixpath.normpath(heap_path) + for target in tmpfs_targets(app): + mount = posixpath.normpath(target) + if path == mount or path.startswith(mount.rstrip("/") + "/"): + return [f"app mounts {target} as a tmpfs, which holds the heap dump path {heap_path}; a tmpfs " + "counts against the memory limit and is gone when the container exits"] + return [] + + +def keycloak_realm(repo_root: Path) -> list[str]: + """10. The Keycloak realm artifact carries no key Keycloak refuses to deserialize.""" + realm = repo_root / REALM + if not realm.is_file(): + return [] + try: + tree = json.loads(realm.read_text(encoding="utf-8")) + except (ValueError, UnicodeDecodeError): + return [f"{REALM} is not valid JSON"] + annotations = sorted(set(underscore_keys(tree))) + if annotations: + return [f"the Keycloak realm carries key(s) Keycloak refuses to deserialize: {', '.join(annotations)}"] + return [] + + +def underscore_keys(tree: object) -> list[str]: + if isinstance(tree, dict): + found = [key for key in tree if key.startswith("_")] + for value in tree.values(): + found += underscore_keys(value) + return found + if isinstance(tree, list): + return [key for item in tree for key in underscore_keys(item)] + return [] + + +def judge_lane(contract: dict, lane: dict, rendered: Rendered, repo_root: Path, heap_path: str) -> list[str]: + """The reasons one lane does not match the contract; empty when it does.""" + if rendered.services_rc is None or rendered.model_rc is None: + return ["the shell left no record of rendering this lane"] + if rendered.services_rc != 0: + return [f"the stack does not render: {' '.join(rendered.services_error.split())}"] + problems = service_set(lane, rendered.services) + if problems: + return problems + try: + model = json.loads(rendered.model) if rendered.model_rc == 0 else None + except ValueError: + model = None + if not isinstance(model, dict) or not isinstance(model.get("services"), dict): + return ["the merged model does not render as JSON"] + return [ + *spring_runtime(lane, model), + *duplicate_mounts(model), + *role_partition(contract, lane), + *application_report(contract, lane), + *redis_authentication(lane, model, repo_root), + *memory_limit(lane), + *heap_dump(model, heap_path), + ] + + +def judge(contract: dict, render_dir: Path, repo_root: Path) -> tuple[list[str], list[str]]: + """The lines for the lanes that matched, and every reason the contract did not.""" + heap_path = dockerfile_heap_dump_path(repo_root) + renderable, problems = lanes(contract, repo_root) + matched: list[str] = [] + for lane in renderable: + lane_problems = judge_lane(contract, lane, recorded(render_dir, lane["id"]), repo_root, heap_path) + if lane_problems: + problems += [f"{lane['id']}: {problem}" for problem in lane_problems] + else: + matched.append(f"{lane['id']}: {','.join(sorted(lane['services']))} @ {lane['springRuntime']}") + problems += keycloak_realm(repo_root) + return matched, problems + + +# ---- files ------------------------------------------------------------------------------------ + +def dockerfile_heap_dump_path(repo_root: Path) -> str: + dockerfile = repo_root / "Dockerfile" + match = HEAP_DUMP_PATH.search(read(dockerfile) or "") + if match is None or not match.group(1): + raise SetupError("the Dockerfile sets no -XX:HeapDumpPath") + return match.group(1) + + +def recorded(render_dir: Path, lane_id: str) -> Rendered: + return Rendered( + services_rc=status(read(render_dir / f"{lane_id}.services.rc")), + services=read(render_dir / f"{lane_id}.services") or "", + services_error=read(render_dir / f"{lane_id}.services.err") or "", + model_rc=status(read(render_dir / f"{lane_id}.json.rc")), + model=read(render_dir / f"{lane_id}.json") or "", + ) + + +def status(text: str | None) -> int | None: + if text is None or not text.strip().isdigit(): + return None + return int(text.strip()) + + +def read(path: Path) -> str | None: + try: + return path.read_text(encoding="utf-8", errors="replace") + except FileNotFoundError: + return None + + +def relative(path: Path, root: Path) -> str: + try: + return str(path.resolve().relative_to(root.resolve())) + except ValueError: + return str(path) + + +def load_contract(path: Path) -> dict: + text = read(path) + if text is None: + raise SetupError(f"missing {path}") + try: + contract = json.loads(text) + except ValueError as error: + raise ContractError(f"{path} is not valid JSON: {error}") from error + if not isinstance(contract, dict): + raise ContractError(f"{path} is not a JSON object") + return contract + + +class ContractError(Exception): + """The contract file cannot be read as a contract; a failure, not a setup problem.""" + + +def main(argv: list[str] | None = None) -> int: + parser = argparse.ArgumentParser(description=__doc__.splitlines()[0]) + parser.add_argument("--repo-root", type=Path, default=DEFAULT_REPO_ROOT, + help="the repository the contract's paths are relative to") + commands = parser.add_subparsers(dest="command", required=True) + version_command = commands.add_parser("version") + version_command.add_argument("contract", type=Path) + version_command.add_argument("actual") + commands.add_parser("lanes").add_argument("contract", type=Path) + judge_command = commands.add_parser("judge") + judge_command.add_argument("contract", type=Path) + judge_command.add_argument("render_dir", type=Path) + args = parser.parse_args(argv) + + try: + contract = load_contract(args.contract) + if args.command == "version": + problems = compose_version(contract, args.actual) + for problem in problems: + print(problem, file=sys.stderr) + if not problems: + print(f"compose version {args.actual.strip().removeprefix('v')} >= {contract['minimumComposeVersion']}") + return 1 if problems else 0 + if args.command == "lanes": + for lane in lanes(contract, args.repo_root)[0]: + print("\t".join([lane["id"], *compose_arguments(contract, lane, args.repo_root)])) + return 0 + matched, problems = judge(contract, args.render_dir, args.repo_root) + except SetupError as error: + print(error, file=sys.stderr) + return SETUP + except ContractError as error: + print(f" FAIL: {error}", file=sys.stderr) + return 1 + for line in matched: + print(line) + for problem in problems: + print(f" FAIL: {problem}", file=sys.stderr) + if problems: + print(f"verify-compose-profile-contracts: {len(problems)} problem(s) against {CONTRACT_LABEL}", + file=sys.stderr) + return 1 + print(f"verify-compose-profile-contracts: all {len(matched)} lanes match {CONTRACT_LABEL}") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/scripts/tests/test_compose_contract_verdict.py b/scripts/tests/test_compose_contract_verdict.py new file mode 100644 index 00000000..8996aa97 --- /dev/null +++ b/scripts/tests/test_compose_contract_verdict.py @@ -0,0 +1,829 @@ +"""scripts/compose-contract-verdict.py의 시험. Compose 계약의 정적 판정이 고장 난 입력을 실패로 보는지 본다: +lane이 없는 계약, 파일이 없는 lane, 렌더 실패와 셸이 남기지 않은 렌더 기록, service 집합·Spring runtime·mount 중복, +role 분할, 기대 vendor가 없는 JPA lane, Redis 계정 대조(비밀번호의 `*`를 포함해), tmpfs 위의 heap dump 경로, +Keycloak realm의 `_` key. 정상 입력은 통과하는지도 같이 본다. 마지막으로 +scripts/verify-compose-profile-contracts.sh를 가짜 `docker`로 돌려, 셸이 판정에 lane 인자와 렌더 결과를 넘기고 +그 rc로 끝나는지 본다. + + python3 -m unittest discover -s scripts/tests +""" + +from __future__ import annotations + +import importlib.util +import io +import json +import os +import shutil +import stat +import subprocess +import sys +import tempfile +import textwrap +import unittest +from contextlib import redirect_stderr, redirect_stdout +from pathlib import Path + +SCRIPTS = Path(__file__).resolve().parent.parent +VERDICT = SCRIPTS / "compose-contract-verdict.py" +SHELL = SCRIPTS / "verify-compose-profile-contracts.sh" +_spec = importlib.util.spec_from_file_location("compose_contract_verdict", VERDICT) +verdict = importlib.util.module_from_spec(_spec) +sys.modules["compose_contract_verdict"] = verdict +_spec.loader.exec_module(verdict) + +CONTRACT_PATH = "src/bootstrap/app/compose-lanes/compose-profile-contracts.json" +HEAP = "/var/tmp/heap" +ACL = "user default off\nuser app on >example-app-password ~prod:* +@all\nuser app-advanced on >example-advanced-password ~prod:* +@all\n" + + +def contract(*lanes: dict, **fields: object) -> dict: + document = { + "minimumComposeVersion": "2.24.4", + "composeFiles": {"base": "compose.yaml", "lane": "lane-services.yaml"}, + "preStartServices": ["schema"], + "oneShotServices": ["smoke"], + "capabilities": ["persistence-jpa", "redis"], + "lanes": list(lanes), + } + document.update(fields) + return document + + +def lane(**fields: object) -> dict: + document = { + "id": "off-local", "composeProfiles": [], "files": ["base"], "springRuntime": "local", + "services": ["app"], "longRunningServices": ["app"], "oneShotServices": [], "blocking": True, + "activationEnv": {}, "expectedCapabilitiesOn": [], "expectedPersistenceVendor": "none", + } + document.update(fields) + return document + + +def app(**fields: object) -> dict: + service = {"environment": {"SPRING_PROFILES_ACTIVE": "local"}, "tmpfs": ["/tmp:mode=1777,size=128m"]} + service.update(fields) + return service + + +def model(**services: dict) -> dict: + return {"services": services or {"app": app()}} + + +class Repository: + """A repository root with the files the verdict reads: compose files, a Dockerfile, an ACL file.""" + + def __init__(self) -> None: + self._directory = tempfile.TemporaryDirectory() + self.root = Path(self._directory.name) + self.write("compose.yaml", "services: {}\n") + self.write("lane-services.yaml", "services: {}\n") + self.write("Dockerfile", f'ENV JAVA_TOOL_OPTIONS="-XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath={HEAP} \\\n') + self.write("compose/redis/acl/lane.acl", ACL) + + def write(self, relative: str, text: str) -> Path: + path = self.root / relative + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(text, encoding="utf-8") + return path + + def close(self) -> None: + self._directory.cleanup() + + +def rendered(services: str = "app\n", document: object = None, services_rc: int | None = 0, + model_rc: int | None = 0, error: str = "") -> verdict.Rendered: + return verdict.Rendered( + services_rc=services_rc, services=services, services_error=error, + model_rc=model_rc, model=json.dumps(model() if document is None else document), + ) + + +class RepositoryTestCase(unittest.TestCase): + + def setUp(self) -> None: + self.repository = Repository() + self.addCleanup(self.repository.close) + self.root = self.repository.root + + +class ContractShapeTest(RepositoryTestCase): + + def test_a_list_entry_that_is_not_a_name_fails_the_lane(self) -> None: + # given: strings() drops such an entry, so the role and report checks would never see it + cases = { + "expectedCapabilitiesOn": [None], + "longRunningServices": ["app", 1], + "services": ["app", ""], + "composeProfiles": [["jpa"]], + "oneShotServices": [None], + "preStartServices": [False], + } + for field, entries in cases.items(): + with self.subTest(field=field): + # when + renderable, problems = verdict.lanes(contract(lane(**{field: entries})), self.root) + + # then + self.assertEqual(renderable, []) + self.assertEqual(problems, [f"off-local: '{field}' holds {json.dumps(entries)}, and every entry must be a name"]) + + def test_a_contract_with_lanes_that_name_existing_files_is_renderable(self) -> None: + # given + document = contract(lane(), lane(id="off-dev", files=["base", "lane"], composeProfiles=["jpa"])) + + # when + renderable, problems = verdict.lanes(document, self.root) + + # then + self.assertEqual(problems, []) + self.assertEqual( + verdict.compose_arguments(document, renderable[1], self.root), + ["-f", str(self.root / "compose.yaml"), "-f", str(self.root / "lane-services.yaml"), "--profile", "jpa"], + ) + + def test_a_contract_with_no_lanes_fails_rather_than_matching_all_of_none(self) -> None: + for lanes in ({"lanes": []}, {"lanes": None}): + with self.subTest(lanes=lanes): + # given + document = contract(**lanes) + + # when + renderable, problems = verdict.lanes(document, self.root) + + # then + self.assertEqual(renderable, []) + self.assertEqual(problems, ["the contract declares no lanes, so nothing would be checked"]) + + def test_a_lane_without_files_fails_rather_than_rendering_whatever_compose_finds(self) -> None: + # given + document = contract(lane(files=[])) + + # when + renderable, problems = verdict.lanes(document, self.root) + + # then + self.assertEqual(renderable, []) + self.assertEqual(len(problems), 1) + self.assertTrue(problems[0].startswith("off-local: names no compose file under 'files'"), problems) + + def test_a_lane_naming_an_unknown_or_missing_file_fails(self) -> None: + # given + (self.root / "lane-services.yaml").unlink() + document = contract(lane(files=["base", "tls", "lane"])) + + # when + _, problems = verdict.lanes(document, self.root) + + # then + self.assertEqual(problems, [ + "off-local: names compose file 'tls', which composeFiles does not list", + "off-local: lane-services.yaml is missing", + ]) + + def test_a_lane_without_the_lists_the_smoke_wrapper_reads_fails(self) -> None: + # given + broken = lane() + del broken["composeProfiles"], broken["expectedCapabilitiesOn"], broken["springRuntime"] + + # when + _, problems = verdict.lanes(contract(broken), self.root) + + # then + self.assertEqual(problems, [ + "off-local: has no 'composeProfiles' list; the smoke wrapper reads it as one", + "off-local: has no 'expectedCapabilitiesOn' list; the smoke wrapper reads it as one", + "off-local: names no springRuntime", + ]) + + def test_two_lanes_with_one_id_fail_because_their_records_would_overwrite_each_other(self) -> None: + # given + document = contract(lane(), lane()) + + # when + renderable, problems = verdict.lanes(document, self.root) + + # then + self.assertEqual(len(renderable), 1) + self.assertEqual(problems, ["off-local: the id is used by more than one lane"]) + + def test_an_id_that_is_not_a_file_name_fails(self) -> None: + # given + document = contract(lane(id="../escape")) + + # when + _, problems = verdict.lanes(document, self.root) + + # then + self.assertEqual(problems, ["lane 0: id '../escape' is not a name such as off-local"]) + + +class ComposeVersionTest(unittest.TestCase): + + def test_a_compose_at_or_above_the_floor_passes(self) -> None: + for actual in ("2.24.4", "v2.29.1", "2.30.0-desktop.1", "3.0"): + with self.subTest(actual=actual): + self.assertEqual(verdict.compose_version(contract(), actual), []) + + def test_a_compose_below_the_floor_fails(self) -> None: + for actual in ("2.24.3", "2.24", "1.29.2"): + with self.subTest(actual=actual): + problems = verdict.compose_version(contract(), actual) + self.assertEqual(problems[0], f"docker compose {actual} is below the required 2.24.4;") + + def test_a_version_that_cannot_be_read_fails(self) -> None: + self.assertEqual( + verdict.compose_version(contract(), ""), + ["docker compose reports '', which is not a version"], + ) + self.assertEqual( + verdict.compose_version(contract(minimumComposeVersion=None), "2.29.1"), + ["minimumComposeVersion '' is not a version such as 2.24.4"], + ) + + +class RenderTest(RepositoryTestCase): + + def judge(self, record: verdict.Rendered, subject: dict | None = None) -> list[str]: + subject = subject or lane() + return verdict.judge_lane(contract(subject), subject, record, self.root, HEAP) + + def test_a_lane_that_renders_its_services_and_a_clean_model_passes(self) -> None: + self.assertEqual(self.judge(rendered()), []) + + def test_a_stack_that_does_not_render_fails_with_what_compose_said(self) -> None: + # given + record = rendered(services="", services_rc=1, error="service \"app\" refers to\nundefined volume\n") + + # when + problems = self.judge(record) + + # then + self.assertEqual(problems, ["the stack does not render: service \"app\" refers to undefined volume"]) + + def test_a_lane_the_shell_left_no_record_for_fails(self) -> None: + for record in (rendered(services_rc=None), rendered(model_rc=None)): + with self.subTest(record=record): + self.assertEqual(self.judge(record), ["the shell left no record of rendering this lane"]) + + def test_a_superset_or_a_subset_of_the_services_fails(self) -> None: + for services in ("app\npostgres\n", ""): + with self.subTest(services=services): + problems = self.judge(rendered(services=services)) + self.assertEqual(len(problems), 1) + self.assertTrue(problems[0].startswith("services are ["), problems) + + def test_the_order_of_the_rendered_services_does_not_matter(self) -> None: + # given + subject = lane(services=["postgres", "app"], longRunningServices=["app", "postgres"]) + document = model(app=app(), postgres={}) + + # then + self.assertEqual(self.judge(rendered(services="app\npostgres\n", document=document), subject), []) + + def test_a_model_that_is_not_json_fails(self) -> None: + # given + record = verdict.Rendered(services_rc=0, services="app\n", services_error="", model_rc=0, model="services:\n") + + # then + self.assertEqual(self.judge(record), ["the merged model does not render as JSON"]) + self.assertEqual(self.judge(rendered(model_rc=15)), ["the merged model does not render as JSON"]) + + def test_another_spring_runtime_fails(self) -> None: + # given + document = model(app=app(environment={"SPRING_PROFILES_ACTIVE": "prod"})) + + # then + self.assertEqual( + self.judge(rendered(document=document)), + ["app renders SPRING_PROFILES_ACTIVE='prod', the contract says 'local'"], + ) + + def test_a_mount_target_declared_twice_fails_naming_the_service(self) -> None: + # given + document = model(app=app(volumes=[{"type": "bind", "source": "/data", "target": "/tmp"}])) + + # then + self.assertEqual(self.judge(rendered(document=document)), ["a mount target is declared twice — app: /tmp"]) + + +class RolePartitionTest(unittest.TestCase): + + def test_a_service_filed_under_exactly_one_role_passes(self) -> None: + # given + subject = lane(services=["app", "schema", "smoke"], preStartServices=["schema"], oneShotServices=["smoke"]) + + # then + self.assertEqual(verdict.role_partition(contract(), subject), []) + + def test_an_unfiled_a_not_rendered_and_a_twice_filed_service_fail(self) -> None: + # given + subject = lane(services=["app", "postgres"], longRunningServices=["app", "redis"], oneShotServices=["app"]) + + # when + problems = verdict.role_partition(contract(oneShotServices=["smoke", "app"]), subject) + + # then + self.assertIn( + "services are not partitioned by role — unfiled=[postgres] not-rendered=[redis] twice=[app]", + problems, + ) + + def test_a_one_shot_listed_as_a_wait_target_fails(self) -> None: + # given + subject = lane(services=["app", "smoke"], longRunningServices=["app", "smoke"]) + + # then + self.assertEqual( + verdict.role_partition(contract(), subject), + ["[smoke] are declared non-waiting but listed as --wait targets"], + ) + + def test_a_service_run_once_but_in_no_catalogue_fails(self) -> None: + # given + subject = lane(services=["app", "probe"], oneShotServices=["probe"]) + + # then + self.assertEqual( + verdict.role_partition(contract(), subject), + ["[probe] are run with `run --rm` but are in neither top-level catalogue"], + ) + + +class ApplicationReportTest(unittest.TestCase): + + def test_a_vendor_that_agrees_with_persistence_jpa_passes(self) -> None: + on = lane(expectedCapabilitiesOn=["persistence-jpa"], expectedPersistenceVendor="postgresql") + self.assertEqual(verdict.application_report(contract(), on), []) + self.assertEqual(verdict.application_report(contract(), lane()), []) + + def test_a_jpa_lane_without_an_expected_vendor_fails(self) -> None: + # given: the smoke wrapper compares the reported vendor with this field, so the lane fails every run + subject = lane(expectedCapabilitiesOn=["persistence-jpa"]) + del subject["expectedPersistenceVendor"] + + # when + problems = verdict.application_report(contract(), subject) + + # then + self.assertEqual(problems, [ + "the expected application report is unreachable — no expectedPersistenceVendor with persistence-jpa on", + ]) + + def test_a_vendor_that_contradicts_persistence_jpa_fails(self) -> None: + cases = { + "none with jpa on": (lane(expectedCapabilitiesOn=["persistence-jpa"]), "vendor none with persistence-jpa on"), + "a vendor with jpa off": (lane(expectedPersistenceVendor="postgresql"), "vendor postgresql with persistence-jpa off"), + } + for case, (subject, reason) in cases.items(): + with self.subTest(case=case): + self.assertEqual( + verdict.application_report(contract(), subject), + [f"the expected application report is unreachable — {reason}"], + ) + + def test_a_capability_outside_the_catalogue_fails(self) -> None: + # given + subject = lane(expectedCapabilitiesOn=["websocket"]) + + # then + self.assertEqual( + verdict.application_report(contract(), subject), + ["the expected application report is unreachable — uncatalogued=[websocket]"], + ) + + +class RedisAuthenticationTest(RepositoryTestCase): + + def environment(self, **overrides: object) -> dict: + env = { + "APP_REDIS_ENABLED": "true", + "APP_REDIS_NAMESPACE_ENVIRONMENT": "prod", + "APP_REDIS_AUTHENTICATION_CREDENTIAL_REFERENCE": "secret://app@environment/REDIS_LANE_APPLICATION_PASSWORD", + "APP_REDIS_AUTHENTICATION_ADVANCED_CREDENTIAL_REFERENCE": + "secret://app-advanced@environment/REDIS_LANE_ADVANCED_PASSWORD", + "REDIS_LANE_APPLICATION_PASSWORD": "example-app-password", + "REDIS_LANE_ADVANCED_PASSWORD": "example-advanced-password", + } + env.update(overrides) + return {key: value for key, value in env.items() if value is not None} + + def redis(self, **fields: object) -> dict: + service = { + "command": ["redis-server", "--appendonly", "no", "--aclfile", "/etc/redis/acl/lane.acl"], + "volumes": [{"type": "bind", "source": str(self.root / "compose/redis/acl"), + "target": "/etc/redis/acl", "read_only": True}], + "healthcheck": {"test": ["CMD-SHELL", "redis-cli --user app --pass \"$$P\" ping"]}, + } + service.update(fields) + return service + + def problems(self, env: dict | None = None, redis: dict | None = None) -> list[str]: + subject = lane(activationEnv=self.environment() if env is None else env) + document = model(app=app(), redis=self.redis() if redis is None else redis) + return verdict.redis_authentication(subject, document, self.root) + + def test_a_lane_that_names_accounts_its_redis_provisions_passes(self) -> None: + self.assertEqual(self.problems(), []) + + def test_a_lane_that_does_not_switch_redis_on_is_not_checked(self) -> None: + self.assertEqual(self.problems(env={"APP_REDIS_ENABLED": "false"}, redis={}), []) + + def test_a_password_with_a_star_does_not_match_an_account_with_another_password(self) -> None: + # given: '*' is a character of the password, not a wildcard + env = self.environment(REDIS_LANE_APPLICATION_PASSWORD="*") + + # then + self.assertEqual( + self.problems(env=env), + ["REDIS_LANE_APPLICATION_PASSWORD is not the password compose/redis/acl/lane.acl gives app"], + ) + + def test_a_wrong_password_fails(self) -> None: + self.assertEqual( + self.problems(env=self.environment(REDIS_LANE_ADVANCED_PASSWORD="example-app-password")), + ["REDIS_LANE_ADVANCED_PASSWORD is not the password compose/redis/acl/lane.acl gives app-advanced"], + ) + + def test_a_user_name_with_a_dot_matches_only_itself(self) -> None: + # given: a regular expression read 'app.x' as 'app' plus any character plus 'x' + self.repository.write("compose/redis/acl/lane.acl", ACL + "user appXx on >example-x-password ~prod:* +@all\n") + env = self.environment(APP_REDIS_AUTHENTICATION_CREDENTIAL_REFERENCE="secret://app.x@environment/X", + X="example-x-password") + + # then + self.assertEqual( + self.problems(env=env), + ["APP_REDIS_AUTHENTICATION_CREDENTIAL_REFERENCE names app.x, which compose/redis/acl/lane.acl does not enable"], + ) + + def test_a_namespace_the_account_may_not_touch_fails(self) -> None: + problems = self.problems(env=self.environment(APP_REDIS_NAMESPACE_ENVIRONMENT="local")) + self.assertEqual(problems, [ + "app may not touch local:*, the namespace this lane writes", + "app-advanced may not touch local:*, the namespace this lane writes", + ]) + + def test_each_way_a_lane_falls_short_is_named(self) -> None: + cases = { + "anonymous": (self.environment(APP_REDIS_AUTHENTICATION_ANONYMOUS_ACCESS_ACCEPTED=True), None, + "accepts anonymous Redis access"), + "no namespace": (self.environment(APP_REDIS_NAMESPACE_ENVIRONMENT=None), None, + "sets no APP_REDIS_NAMESPACE_ENVIRONMENT"), + "no aclfile": (None, self.redis(command=["redis-server"]), "starts Redis without --aclfile"), + "aclfile is the last word": (None, self.redis(command=["redis-server", "--aclfile"]), + "starts Redis without --aclfile"), + "writable mount": (None, self.redis(volumes=[{"type": "bind", "source": str(self.root / "compose/redis/acl"), + "target": "/etc/redis/acl"}]), + "which no read-only bind mount of a repository file provides"), + "healthcheck as default user": (None, self.redis(healthcheck={"test": ["CMD", "redis-cli", "ping"]}), + "the Redis healthcheck does not authenticate"), + "malformed reference": (self.environment(APP_REDIS_AUTHENTICATION_CREDENTIAL_REFERENCE="secret://env/X"), + None, "is 'secret://env/X', not secret://@environment/"), + "unset variable": (self.environment(REDIS_LANE_APPLICATION_PASSWORD=None), None, + "reads REDIS_LANE_APPLICATION_PASSWORD, which the lane does not supply"), + } + for case, (env, redis, reason) in cases.items(): + with self.subTest(case=case): + problems = self.problems(env=env, redis=redis) + self.assertTrue(any(reason in problem for problem in problems), problems) + + def test_an_acl_file_that_leaves_the_default_user_on_or_enables_a_user_twice_fails(self) -> None: + # given + self.repository.write("compose/redis/acl/lane.acl", ACL.replace("user default off\n", "") + + "user app on >example-app-password ~prod:* +@all\n") + + # then + self.assertEqual(self.problems(), [ + "compose/redis/acl/lane.acl leaves the default user on, which makes every account restriction optional", + "compose/redis/acl/lane.acl enables app on more than one line, which Redis refuses to load", + ]) + + def test_an_acl_file_mounted_as_a_file_is_read(self) -> None: + # given + mount = {"type": "bind", "source": str(self.root / "compose/redis/acl/lane.acl"), + "target": "/etc/redis/acl/lane.acl", "read_only": True} + + # then + self.assertEqual(self.problems(redis=self.redis(volumes=[mount])), []) + + +class HeapDumpTest(unittest.TestCase): + + def test_a_tmpfs_away_from_the_heap_dump_path_passes(self) -> None: + self.assertEqual(verdict.heap_dump(model(), HEAP), []) + self.assertEqual(verdict.heap_dump(model(app=app(tmpfs=["/var/tmp/heapless"])), HEAP), []) + + def test_a_tmpfs_at_the_path_or_a_directory_above_it_fails(self) -> None: + # given: only an exact entry of the short list was compared + cases = { + "short syntax at the path": app(tmpfs=["/tmp", f"{HEAP}:size=1g"]), + "short syntax above the path": app(tmpfs=["/var/tmp:size=1g"]), + "trailing slash above the path": app(tmpfs=["/var/tmp/"]), + "long syntax at the path": app(volumes=[{"type": "tmpfs", "target": HEAP}]), + "long syntax above the path": app(volumes=[{"type": "tmpfs", "target": "/var"}]), + } + for case, service in cases.items(): + with self.subTest(case=case): + problems = verdict.heap_dump(model(app=service), HEAP) + self.assertEqual(len(problems), 1) + self.assertIn(f"which holds the heap dump path {HEAP}", problems[0]) + + def test_a_volume_or_bind_mount_at_the_heap_dump_path_is_not_a_tmpfs(self) -> None: + for kind, source in (("volume", "dumps"), ("bind", "./build/heap")): + with self.subTest(kind=kind): + service = app(volumes=[{"type": kind, "source": source, "target": HEAP}]) + self.assertEqual(verdict.heap_dump(model(app=service), HEAP), []) + + +class MemoryLimitTest(unittest.TestCase): + + def test_a_compose_memory_size_or_none_passes(self) -> None: + self.assertEqual(verdict.memory_limit(lane(appMemoryLimit="1g")), []) + self.assertEqual(verdict.memory_limit(lane()), []) + + def test_a_size_compose_does_not_read_fails(self) -> None: + for limit in ("1G", "1.5g", "1024", "0m"): + with self.subTest(limit=limit): + self.assertEqual( + verdict.memory_limit(lane(appMemoryLimit=limit)), + [f"appMemoryLimit '{limit}' is not a Compose memory size such as 1g"], + ) + + +class KeycloakRealmTest(RepositoryTestCase): + + def test_no_realm_or_a_realm_without_annotations_passes(self) -> None: + self.assertEqual(verdict.keycloak_realm(self.root), []) + self.repository.write(verdict.REALM, json.dumps({"realm": "ca", "clients": [{"clientId": "web"}]})) + self.assertEqual(verdict.keycloak_realm(self.root), []) + + def test_an_annotation_key_anywhere_in_the_tree_fails(self) -> None: + # given + self.repository.write(verdict.REALM, json.dumps({"_comment": "x", "clients": [{"_flowComment": "y"}]})) + + # then + self.assertEqual( + verdict.keycloak_realm(self.root), + ["the Keycloak realm carries key(s) Keycloak refuses to deserialize: _comment, _flowComment"], + ) + + def test_a_realm_that_is_not_json_fails(self) -> None: + self.repository.write(verdict.REALM, "{") + self.assertEqual(verdict.keycloak_realm(self.root), [f"{verdict.REALM} is not valid JSON"]) + + +class CommandLineTest(RepositoryTestCase): + + def record(self, directory: Path, lane_id: str, services: str = "app\n", document: object = None) -> None: + (directory / f"{lane_id}.services").write_text(services, encoding="utf-8") + (directory / f"{lane_id}.services.err").write_text("", encoding="utf-8") + (directory / f"{lane_id}.services.rc").write_text("0\n", encoding="utf-8") + (directory / f"{lane_id}.json").write_text(json.dumps(document or model()), encoding="utf-8") + (directory / f"{lane_id}.json.rc").write_text("0\n", encoding="utf-8") + + def run_judge(self, document: dict) -> tuple[int, str, str]: + path = self.repository.write(CONTRACT_PATH, json.dumps(document)) + stdout, stderr = io.StringIO(), io.StringIO() + with redirect_stdout(stdout), redirect_stderr(stderr): + rc = verdict.main(["--repo-root", str(self.root), "judge", str(path), str(self.root / "rendered")]) + return rc, stdout.getvalue(), stderr.getvalue() + + def setUp(self) -> None: + super().setUp() + (self.root / "rendered").mkdir() + + def test_every_lane_matching_exits_zero_naming_each(self) -> None: + # given + self.record(self.root / "rendered", "off-local") + + # when + rc, stdout, stderr = self.run_judge(contract(lane())) + + # then + self.assertEqual((rc, stderr), (0, "")) + self.assertEqual(stdout.splitlines(), [ + "off-local: app @ local", + f"verify-compose-profile-contracts: all 1 lanes match {CONTRACT_PATH}", + ]) + + def test_each_lane_judgement_fails_the_command_on_its_own(self) -> None: + # given: one fault per case, each seen by one judgement only, so a judgement left out of + # judge_lane passes its case + no_vendor = lane(expectedCapabilitiesOn=["persistence-jpa"]) + del no_vendor["expectedPersistenceVendor"] + redis_on = {"APP_REDIS_ENABLED": "true", "APP_REDIS_NAMESPACE_ENVIRONMENT": "prod"} + cases = { + "role partition": (lane(longRunningServices=[]), model(), + "services are not partitioned by role — unfiled=[app]"), + "application report": (no_vendor, model(), + "no expectedPersistenceVendor with persistence-jpa on"), + "redis authentication": (lane(activationEnv=redis_on), model(), + "starts Redis without --aclfile"), + "memory limit": (lane(appMemoryLimit="1G"), model(), + "appMemoryLimit '1G' is not a Compose memory size such as 1g"), + "heap dump": (lane(), model(app=app(tmpfs=["/var/tmp:size=64m"])), + f"which holds the heap dump path {HEAP}"), + } + for case, (subject, document, reason) in cases.items(): + with self.subTest(case=case): + self.record(self.root / "rendered", "off-local", document=document) + + # when + rc, stdout, stderr = self.run_judge(contract(subject)) + + # then + self.assertEqual((rc, stdout), (1, "")) + failures = [line for line in stderr.splitlines() if line.startswith(" FAIL: ")] + self.assertEqual(len(failures), 1, stderr) + self.assertTrue(failures[0].startswith(" FAIL: off-local: "), failures[0]) + self.assertIn(reason, failures[0]) + + def test_a_realm_annotation_fails_the_command_although_every_lane_matches(self) -> None: + # given + self.record(self.root / "rendered", "off-local") + self.repository.write(verdict.REALM, json.dumps({"_comment": "x"})) + + # when + rc, stdout, stderr = self.run_judge(contract(lane())) + + # then + self.assertEqual(rc, 1) + self.assertEqual(stdout, "off-local: app @ local\n") + self.assertIn(" FAIL: the Keycloak realm carries key(s) Keycloak refuses to deserialize: _comment\n", stderr) + + def test_a_failing_lane_exits_one_and_the_other_lanes_are_still_judged(self) -> None: + # given: off-dev has no record at all, and off-local renders a service too many + self.record(self.root / "rendered", "off-local", services="app\nextra\n") + + # when + rc, stdout, stderr = self.run_judge(contract(lane(), lane(id="off-dev"))) + + # then + self.assertEqual(rc, 1) + self.assertEqual(stdout, "") + self.assertEqual(stderr.splitlines(), [ + " FAIL: off-local: services are [app,extra], the contract says [app]", + " FAIL: off-dev: the shell left no record of rendering this lane", + f"verify-compose-profile-contracts: 2 problem(s) against {CONTRACT_PATH}", + ]) + + def test_a_dockerfile_without_a_heap_dump_path_is_a_setup_error(self) -> None: + # given + self.repository.write("Dockerfile", "FROM eclipse-temurin:21-jre\n") + + # when + rc, _, stderr = self.run_judge(contract(lane())) + + # then + self.assertEqual((rc, stderr), (78, "the Dockerfile sets no -XX:HeapDumpPath\n")) + + def test_a_contract_that_is_not_json_fails(self) -> None: + # given + path = self.repository.write(CONTRACT_PATH, "{") + + # when + with redirect_stderr(io.StringIO()) as stderr: + rc = verdict.main(["--repo-root", str(self.root), "lanes", str(path)]) + + # then + self.assertEqual(rc, 1) + self.assertIn("is not valid JSON", stderr.getvalue()) + + +FAKE_DOCKER = """\ +#!{python} +# Answers `docker compose ...` the way the contract script calls it, from files beside this script. +import pathlib, sys +here = pathlib.Path(__file__).resolve().parent +with open(here / "calls.log", "a", encoding="utf-8") as log: + log.write(" ".join(sys.argv[1:]) + "\\n") +args = sys.argv[1:] +sys.stdin.read() # as a call that reads stdin would: the shell's lane list must not be what it reads +if args[:3] == ["compose", "version", "--short"]: + print((here / "version").read_text().strip()) + sys.exit(0) +stack = "+".join(pathlib.Path(args[i + 1]).name for i, a in enumerate(args) if a == "-f") +kind = "json" if "--format" in args else "services" +answer = here / f"{{stack}}.{{kind}}" +if not answer.exists(): + print(f"no such stack: {{stack}}", file=sys.stderr) + sys.exit(15) +sys.stdout.write(answer.read_text()) +status = here / f"{{stack}}.{{kind}}.rc" +sys.exit(int(status.read_text()) if status.exists() else 0) +""" + + +class ContractScriptTest(RepositoryTestCase): + # The judgements above are only a gate while the shell gives them what docker rendered and exits + # with their status. This runs the real shell against a repository whose `docker` is a fake. + + def setUp(self) -> None: + super().setUp() + (self.root / "scripts").mkdir() + for script in (SHELL, VERDICT): + shutil.copy(script, self.root / "scripts" / script.name) + self.fake = self.root / "fake-bin" + self.fake.mkdir() + docker = self.fake / "docker" + docker.write_text(FAKE_DOCKER.format(python=sys.executable), encoding="utf-8") + docker.chmod(docker.stat().st_mode | stat.S_IXUSR) + (self.fake / "version").write_text("2.29.1\n", encoding="utf-8") + self.answer("compose.yaml", "app\n", model()) + self.answer("compose.yaml+lane-services.yaml", "app\nschema\n", model(app=app(), schema={})) + + def answer(self, stack: str, services: str, document: dict) -> None: + (self.fake / f"{stack}.services").write_text(services, encoding="utf-8") + (self.fake / f"{stack}.json").write_text(json.dumps(document), encoding="utf-8") + + def run_script(self, document: dict) -> subprocess.CompletedProcess: + self.repository.write(CONTRACT_PATH, json.dumps(document)) + env = dict(os.environ, PATH=f"{self.fake}{os.pathsep}{os.environ.get('PATH', '')}", TMPDIR=str(self.root)) + return subprocess.run(["bash", str(self.root / "scripts" / SHELL.name)], + stdin=subprocess.DEVNULL, capture_output=True, text=True, env=env, check=False) + + def calls(self) -> list[str]: + log = self.fake / "calls.log" + return log.read_text(encoding="utf-8").splitlines() if log.exists() else [] + + def two_lanes(self) -> dict: + return contract(lane(), lane(id="schema-lane", files=["base", "lane"], composeProfiles=["jpa"], + services=["app", "schema"], preStartServices=["schema"])) + + def test_lanes_that_render_what_they_claim_pass_and_each_is_rendered_with_its_files_and_profiles(self) -> None: + # when + result = self.run_script(self.two_lanes()) + + # then + self.assertEqual(result.returncode, 0, result.stderr) + self.assertEqual(result.stdout.splitlines(), [ + "compose version 2.29.1 >= 2.24.4", + "off-local: app @ local", + "schema-lane: app,schema @ local", + f"verify-compose-profile-contracts: all 2 lanes match {CONTRACT_PATH}", + ]) + base, extra = self.root / "compose.yaml", self.root / "lane-services.yaml" + self.assertEqual(self.calls(), [ + "compose version --short", + f"compose -f {base} config --services", + f"compose -f {base} config --format json", + f"compose -f {base} -f {extra} --profile jpa config --services", + f"compose -f {base} -f {extra} --profile jpa config --format json", + ]) + self.assertEqual(sorted(path.name for path in self.root.glob("compose-contract.*")), []) + + def test_a_lane_whose_stack_does_not_render_fails_and_the_next_lane_is_still_rendered(self) -> None: + # given + (self.fake / "compose.yaml.services").unlink() + + # when + result = self.run_script(self.two_lanes()) + + # then + self.assertEqual(result.returncode, 1) + self.assertIn(" FAIL: off-local: the stack does not render: no such stack: compose.yaml\n", result.stderr) + self.assertIn("schema-lane: app,schema @ local\n", result.stdout) + + def test_a_model_render_that_exits_non_zero_fails_although_it_printed_json(self) -> None: + # given: the JSON is a model that would pass; only the exit status says the render failed + (self.fake / "compose.yaml.json.rc").write_text("1\n", encoding="utf-8") + + # when + result = self.run_script(self.two_lanes()) + + # then + self.assertEqual(result.returncode, 1) + self.assertIn(" FAIL: off-local: the merged model does not render as JSON\n", result.stderr) + self.assertIn("schema-lane: app,schema @ local\n", result.stdout) + + def test_a_contract_with_no_lanes_fails(self) -> None: + # when + result = self.run_script(contract()) + + # then + self.assertEqual(result.returncode, 1) + self.assertIn("the contract declares no lanes", result.stderr) + + def test_a_compose_below_the_floor_fails_before_any_lane_is_rendered(self) -> None: + # given + (self.fake / "version").write_text("2.20.0\n", encoding="utf-8") + + # when + result = self.run_script(self.two_lanes()) + + # then + self.assertEqual(result.returncode, 1) + self.assertIn("docker compose 2.20.0 is below the required 2.24.4;", result.stderr) + self.assertEqual(self.calls(), ["compose version --short"]) + + def test_the_shell_keeps_no_judgement_of_its_own(self) -> None: + # Every judgement is in the verdict, where the cases above can reach it. + script = SHELL.read_text(encoding="utf-8") + commands = "\n".join(line for line in script.splitlines() if not line.lstrip().startswith("#")) + self.assertNotRegex(commands, r"\bjq\b") + self.assertRegex(script, r'\npython3 "\$\{VERDICT\}" judge "\$\{CONTRACTS\}" "\$\{RENDERED\}"\n$') + + +if __name__ == "__main__": + unittest.main() diff --git a/scripts/verify-compose-profile-contracts.sh b/scripts/verify-compose-profile-contracts.sh index 1c5e4c52..c7811686 100755 --- a/scripts/verify-compose-profile-contracts.sh +++ b/scripts/verify-compose-profile-contracts.sh @@ -4,6 +4,12 @@ # Called by: the pull-request stage `prCheck` (`verifyComposeProfiles`, root build.gradle) and # scripts/run-compose-runtime-smoke.sh before it starts the lanes. # +# This file keeps the docker calls and nothing else. Which lanes to render and with which files and +# profiles, and every judgement below, are scripts/compose-contract-verdict.py, whose cases in +# scripts/tests try each judgement on broken input without Docker. Each judgement used to be jq here, +# and a jq branch could not be tried on a broken input: an empty lane list passed as "all 0 lanes +# match", and so did a JPA lane with no expected vendor and a heap dump path under a tmpfs. +# # 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 @@ -27,252 +33,54 @@ # 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). +# 9. the application's heap dump path (-XX:HeapDumpPath in the Dockerfile) is on no tmpfs, neither +# one at that path nor one at a directory above it, 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 to deserialize, because the import +# fails on one and the container exits before the lane reaches what it was testing. # # 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 +VERDICT="${REPO_ROOT}/scripts/compose-contract-verdict.py" -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 python3 >/dev/null 2>&1 || { echo "python3 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; } +cd "${REPO_ROOT}" -# ---- 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}" +RENDERED="$(mktemp -d "${TMPDIR:-/tmp}/compose-contract.XXXXXX")" +trap 'rm -rf "${RENDERED}"' EXIT -# ---- 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}")" +# 1. The version is judged before anything renders: an older Compose fails the dev overlay's render +# with a merge error that says nothing about the version. +compose_version="$(docker compose version --short)" +python3 "${VERDICT}" version "${CONTRACTS}" "${compose_version}" - 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}") +# Every lane the contract lets the verdict render, as its id and its `docker compose` arguments. A +# lane it cannot render (no files, an unknown file) is not listed; `judge` reports it. +python3 "${VERDICT}" lanes "${CONTRACTS}" >"${RENDERED}/lanes.tsv" - profile_args=() - while read -r profile; do - [[ -n "${profile}" ]] && profile_args+=(--profile "${profile}") - done < <(jq -r '.composeProfiles[]' <<<"${lane}") +# Each call's output and exit status go to files, and the status is read outside any condition so a +# failed render is recorded as itself. stderr of `config --services` goes to its own file rather than +# into the list: merged with `2>&1`, Compose's warning about an unset interpolation variable arrived +# as an extra "service" and twelve lanes failed with a log line in place of a container name. +# stdin is /dev/null: the loop reads the lane list from stdin, and a call that read it would leave +# the lanes after it without a record. +while IFS=$'\t' read -r -a fields; do + lane="${RENDERED}/${fields[0]}" + args=("${fields[@]:1}") + status=0 + docker compose "${args[@]}" config --services "${lane}.services" 2>"${lane}.services.err" || status=$? + echo "${status}" >"${lane}.services.rc" + status=0 + docker compose "${args[@]}" config --format json "${lane}.json" 2>"${lane}.json.err" || status=$? + echo "${status}" >"${lane}.json.rc" +done <"${RENDERED}/lanes.tsv" - # 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" +# 2-10, and the shape of every lane. +python3 "${VERDICT}" judge "${CONTRACTS}" "${RENDERED}" -- 2.54.0