diff --git a/.gitea/workflows/main.yml b/.gitea/workflows/main.yml index 29de8acd..eebaff66 100644 --- a/.gitea/workflows/main.yml +++ b/.gitea/workflows/main.yml @@ -297,19 +297,28 @@ jobs: steps: - uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 # The NFS server is the host kernel's nfsd, which a container cannot load: the runner's daemon - # has no /lib/modules. Without the module the server exits at once and the compose step only - # says "dependency failed to start" (runs 52 and 63). The runner host loads it once, at boot: - # echo nfsd | sudo tee /etc/modules-load.d/nfsd.conf && sudo modprobe nfsd - - name: The runner host has the nfsd kernel module + # has no /lib/modules. The server image (erichough/nfs-server 2.2.1, entrypoint.sh + # init_runtime_assertions) exits at once unless both nfs and nfsd are loaded, and nfsd does not + # pull in nfs. The runner host loads both once, and at every boot: + # printf 'nfs\nnfsd\n' | sudo tee /etc/modules-load.d/nfsd.conf && sudo modprobe -a nfs nfsd + - name: The runner host has the nfs and nfsd kernel modules run: | - grep -qw nfsd /proc/filesystems || { - echo "fileserver-nfs: the runner host kernel has no nfsd module; load it on the host:" >&2 - echo " echo nfsd | sudo tee /etc/modules-load.d/nfsd.conf && sudo modprobe nfsd" >&2 + missing="" + for module in nfs nfsd; do grep -qw "${module}" /proc/filesystems || missing="${missing} ${module}"; done + [ -z "${missing}" ] || { + echo "fileserver-nfs: the runner host kernel lacks:${missing}; load them on the host:" >&2 + echo " printf 'nfs\\nnfsd\\n' | sudo tee /etc/modules-load.d/nfsd.conf && sudo modprobe -a nfs nfsd" >&2 exit 1 } - uses: ./.gitea/actions/setup-java-gradle - run: docker compose -f src/adapter/outbound/fileserver/compose/nfs/compose.yml up -d --wait - - run: ./gradlew :adapter:outbound:fileserver:test --tests '*NfsAmbiguityIntegrationTest' + # --rerun: FILESERVER_NFS_TESTS is read at run time, not a task input, so without it an + # unchanged fileserver comes back FROM-CACHE and the job is green without touching NFS. + - run: ./gradlew :adapter:outbound:fileserver:test --tests '*NfsAmbiguityIntegrationTest' --rerun + # The compose step says only "exited (1)"; why the server or client stopped is in their logs, + # and the step below removes the containers. + - if: ${{ failure() }} + run: docker compose -f src/adapter/outbound/fileserver/compose/nfs/compose.yml logs --no-color --timestamps - if: ${{ always() }} run: docker compose -f src/adapter/outbound/fileserver/compose/nfs/compose.yml down -v diff --git a/docs/fileserver/storage-certification.md b/docs/fileserver/storage-certification.md index 34638589..7582a973 100644 --- a/docs/fileserver/storage-certification.md +++ b/docs/fileserver/storage-certification.md @@ -46,11 +46,18 @@ ## 네트워크 파일 시스템 +호스트 커널에 `nfs`·`nfsd` 모듈이 둘 다 올라와 있어야 한다. 서버 이미지는 둘 중 하나라도 없으면 바로 +끝나고, `nfsd`를 올려도 `nfs`는 따라오지 않는다. 올리는 명령은 `.gitea/workflows/main.yml` +`fileserver-nfs-ambiguity` job 주석과 같다. + ```bash docker compose -f src/adapter/outbound/fileserver/compose/nfs/compose.yml up -d -FILESERVER_NFS_TESTS=true ./gradlew :adapter:outbound:fileserver:test +FILESERVER_NFS_TESTS=true ./gradlew :adapter:outbound:fileserver:test --rerun ``` +`--rerun`을 붙이는 이유: `FILESERVER_NFS_TESTS`는 시험이 실행 중에 읽는 환경 변수라 태스크 입력이 아니다. env +없이 한 번 돈 뒤 env를 켜고 다시 돌면 태스크가 `UP-TO-DATE`로 끝나 NFS 시험이 돌지 않는다. + mount는 일부러 `hard`다. `soft` mount는 느린 서버를 짧게 끝난 쓰기로 바꾼다. 이 설계가 받아들이지 않는 바로 그 손상이다. diff --git a/src/adapter/outbound/fileserver/compose/nfs/compose.yml b/src/adapter/outbound/fileserver/compose/nfs/compose.yml index b34eba6f..e38c5dd8 100644 --- a/src/adapter/outbound/fileserver/compose/nfs/compose.yml +++ b/src/adapter/outbound/fileserver/compose/nfs/compose.yml @@ -16,7 +16,7 @@ services: nfs-server: - image: erichough/nfs-server:2.2.1 + image: erichough/nfs-server:2.2.1@sha256:1efd4ece380c5ba27479417585224ef857006daa46ab84560a28c1224bc71e9e container_name: fileserver-nfs-server privileged: true environment: @@ -36,7 +36,7 @@ services: retries: 10 nfs-client: - image: eclipse-temurin:21-jdk + image: eclipse-temurin:21-jdk@sha256:8ad118b146aa92da815b576441acd6b42b38236797ad0b6edc8c200b85bb0734 container_name: fileserver-nfs-client privileged: true depends_on: diff --git a/src/bootstrap/app/build.gradle b/src/bootstrap/app/build.gradle index e7e93770..16068210 100644 --- a/src/bootstrap/app/build.gradle +++ b/src/bootstrap/app/build.gradle @@ -376,6 +376,8 @@ def repositoryContractInputs = files( include 'src/bootstrap/app/compose-lanes/**' // The release data a capability leaf owns (readiness cards, release registries). include 'src/adapter/outbound/*/release/**' + // The Compose files outbound leaves keep; workflow steps start some with `-f` (digests). + include 'src/adapter/outbound/*/compose/**' exclude '**/*.md' exclude repositoryContractExcludes }) diff --git a/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/DeveloperExperienceContractTest.java b/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/DeveloperExperienceContractTest.java index daba9568..44d552a1 100644 --- a/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/DeveloperExperienceContractTest.java +++ b/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/DeveloperExperienceContractTest.java @@ -9,10 +9,15 @@ import java.io.IOException; import java.nio.file.Files; import java.nio.file.Path; import java.time.Duration; +import java.util.ArrayList; import java.util.List; import java.util.Map; +import java.util.Set; +import java.util.TreeMap; +import java.util.TreeSet; import java.util.regex.Matcher; import java.util.regex.Pattern; +import java.util.stream.Stream; import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Tag; import org.junit.jupiter.api.Test; @@ -41,6 +46,30 @@ class DeveloperExperienceContractTest { private static final String MAIN_WORKFLOW = ".gitea/workflows/main.yml"; private static final String RELEASE_WORKFLOW = ".gitea/workflows/release.yml"; + /** The nightly job that runs the fileserver tests against a real NFS server, and its Compose. */ + private static final String NFS_JOB = "fileserver-nfs-ambiguity"; + + private static final String NFS_COMPOSE = + "src/adapter/outbound/fileserver/compose/nfs/compose.yml"; + + /** Compose's global options that take a value: the subcommand is the first word after them. */ + private static final Set COMPOSE_OPTIONS_WITH_A_VALUE = + Set.of( + "-f", + "--file", + "-p", + "--project-name", + "--project-directory", + "--env-file", + "--profile", + "--ansi", + "--progress", + "--parallel"); + + private static final Pattern COMPOSE_IMAGE_LINE = + Pattern.compile("^\\s*image:\\s*[\"']?([^\"'\\s#]+)"); + private static final Pattern IMAGE_DIGEST = Pattern.compile("@sha256:[0-9a-f]{64}$"); + // The workflow-mutation fixtures that stood here are gone with the tests that used them: a // hex-escaped `uses:`, a line-continued action reference, a `run:` block impersonating a // validation step, a bare `if: always()` versus the guarded form, a gate-matrix step. Every one @@ -351,6 +380,110 @@ class DeveloperExperienceContractTest { .noneMatch(step -> step instanceof Map map && map.containsKey("uses")); } + @Test + @Tag("repository-contract") + @DisplayName("NFS nightly의 호스트 확인 step은 서버 이미지가 요구하는 nfs·nfsd 두 모듈을 다 보고, 둘 다 올리는 명령을 안내한다") + void nfsHostCheckLooksForBothModulesTheServerImageRequires() throws IOException { + // given + Pattern moduleLoop = Pattern.compile("\\bfor\\s+\\w+\\s+in\\s+([^;\\n]+?)\\s*;\\s*do\\b"); + Pattern loadHint = Pattern.compile("\\bmodprobe\\s+-a((?:\\s+[\\w-]+)+)"); + Pattern bootList = + Pattern.compile("\\bprintf\\s+'([^']*)'\\s*\\|\\s*sudo\\s+tee\\s+/etc/modules-load\\.d/"); + + // when + List checks = + nfsJobSteps().stream() + .map(DeveloperExperienceContractTest::stepRun) + .filter(run -> run.contains("/proc/filesystems")) + .toList(); + + // then + assertThat(checks) + .as("the one step that reads /proc/filesystems") + .singleElement() + .satisfies( + check -> { + assertThat(wordsMatchedBy(moduleLoop, check)) + .as("the modules the check looks for") + .containsExactlyInAnyOrder("nfs", "nfsd"); + assertThat(wordsMatchedBy(loadHint, check)) + .as("the modules the printed command loads now") + .containsExactlyInAnyOrder("nfs", "nfsd"); + assertThat(printfLines(groupMatchedBy(bootList, check))) + .as("the modules the printed command loads at every boot") + .containsExactlyInAnyOrder("nfs", "nfsd"); + }); + } + + @Test + @Tag("repository-contract") + @DisplayName( + "NFS nightly의 Gradle step은 --rerun으로 돈다: FILESERVER_NFS_TESTS는 태스크 입력이 아니어서, --rerun이 없으면 캐시가 NFS 없이 초록을 돌려준다") + void nfsJobRerunsItsTestsInsteadOfTakingThemFromTheBuildCache() throws IOException { + // The flag as a whole word anywhere in the script, so a Gradle call wrapped in a container's + // `bash -c "…"` still counts. + Pattern rerun = Pattern.compile("(? gradleRuns = + nfsJobSteps().stream() + .map(DeveloperExperienceContractTest::stepRun) + .filter(run -> run.contains("gradlew")) + .toList(); + + assertThat(gradleRuns) + .as("the steps that run the NFS tests with Gradle") + .isNotEmpty() + .allSatisfy(run -> assertThat(run).as(run).containsPattern(rerun)); + } + + @Test + @Tag("repository-contract") + @DisplayName("NFS nightly는 실패하면 컨테이너를 지우는 down step보다 먼저 compose 로그를 남긴다") + void nfsJobPrintsTheComposeLogsOnFailureBeforeRemovingTheContainers() throws IOException { + // given + List> composeSteps = + nfsJobSteps().stream() + .filter(step -> scriptWords(stepRun(step)).contains(NFS_COMPOSE)) + .toList(); + + // when + List subcommands = + composeSteps.stream().map(step -> composeSubcommand(stepRun(step))).toList(); + List logsConditions = + composeSteps.stream() + .filter(step -> composeSubcommand(stepRun(step)).equals("logs")) + .map(step -> String.valueOf(step.get("if"))) + .toList(); + + // then + assertThat(subcommands) + .as("what the job asks %s to do, in order", NFS_COMPOSE) + .containsSubsequence("logs", "down"); + assertThat(logsConditions) + .as("the logs step runs when an earlier step failed") + .singleElement() + .asString() + .contains("failure()"); + } + + @Test + @Tag("repository-contract") + @DisplayName("workflow step이 docker compose -f로 띄우는 compose 파일의 image는 모두 sha256 digest로 고정한다") + void composeFilesAWorkflowStepStartsPinEveryImageByDigest() throws IOException { + // given + Set composeFiles = composeFilesStartedByWorkflowSteps(); + + // when + Map> unpinned = imagesWithoutADigest(composeFiles); + + // then + assertThat(unpinned) + .as( + "the Compose files workflow steps start with -f, each with its image lines lacking a digest") + .isNotEmpty() + .allSatisfy((file, images) -> assertThat(images).as(file).isEmpty()); + } + @Test @Tag("repository-contract") @DisplayName("compose 종료 유예 시간은 웹 drain, async 대기, preStop, 여유를 모두 더한 값 이상이다") @@ -601,6 +734,128 @@ class DeveloperExperienceContractTest { return (String) value; } + private static List> nfsJobSteps() throws IOException { + Map job = requireMap(requireMap(parseYamlMap(read(MAIN_WORKFLOW)), "jobs"), NFS_JOB); + return requireList(job, "steps").stream().>map(step -> (Map) step).toList(); + } + + /** A step's shell script, or "" for a step that uses an action. */ + private static String stepRun(Map step) { + return step.get("run") instanceof String run ? run : ""; + } + + /** The word after the NFS Compose file in a {@code docker compose -f } run. */ + private static String composeSubcommand(String run) { + List words = scriptWords(run); + int file = words.indexOf(NFS_COMPOSE); + return file >= 0 && file + 1 < words.size() ? words.get(file + 1) : ""; + } + + /** + * Every file a {@code docker compose -f } names in a step of {@code .gitea/workflows/*} or + * {@code .gitea/actions//action.yml}. Compose a script starts is not one of them. + */ + private static Set composeFilesStartedByWorkflowSteps() throws IOException { + List definitions = new ArrayList<>(); + try (Stream workflows = Files.list(REPOSITORY_ROOT.resolve(".gitea/workflows"))) { + workflows.filter(path -> path.toString().matches(".*\\.ya?ml")).forEach(definitions::add); + } + try (Stream actions = Files.list(REPOSITORY_ROOT.resolve(".gitea/actions"))) { + actions + .flatMap(action -> Stream.of(action.resolve("action.yml"), action.resolve("action.yaml"))) + .filter(Files::isRegularFile) + .forEach(definitions::add); + } + Set files = new TreeSet<>(); + for (Path definition : definitions) { + stepRuns(parseYamlMap(Files.readString(definition))) + .forEach(run -> files.addAll(composeFilesNamedIn(run))); + } + return files; + } + + /** Every {@code run:} script anywhere in a parsed workflow or action. */ + private static Stream stepRuns(Object node) { + if (node instanceof Map map) { + return map.entrySet().stream() + .flatMap( + entry -> + "run".equals(entry.getKey()) && entry.getValue() instanceof String run + ? Stream.of(run) + : stepRuns(entry.getValue())); + } + return node instanceof List list + ? list.stream().flatMap(DeveloperExperienceContractTest::stepRuns) + : Stream.empty(); + } + + /** The {@code -f}/{@code --file} values among the global options of each docker compose call. */ + private static List composeFilesNamedIn(String run) { + List words = scriptWords(run); + List files = new ArrayList<>(); + for (int docker = 0; docker + 1 < words.size(); docker++) { + if (!words.get(docker).equals("docker") || !words.get(docker + 1).equals("compose")) { + continue; + } + int next = docker + 2; + while (next < words.size() && words.get(next).startsWith("-")) { + String option = words.get(next++); + if (option.startsWith("--file=")) { + files.add(option.substring("--file=".length())); + } else if (COMPOSE_OPTIONS_WITH_A_VALUE.contains(option) && next < words.size()) { + String value = words.get(next++); + if (option.equals("-f") || option.equals("--file")) { + files.add(value); + } + } + } + } + return files; + } + + /** Per Compose file, its {@code image:} lines (numbered) whose reference has no digest. */ + private static Map> imagesWithoutADigest(Set composeFiles) + throws IOException { + Map> unpinned = new TreeMap<>(); + for (String file : composeFiles) { + List lines = read(file).lines().toList(); + List withoutDigest = new ArrayList<>(); + for (int line = 0; line < lines.size(); line++) { + Matcher image = COMPOSE_IMAGE_LINE.matcher(lines.get(line)); + if (image.find() && !IMAGE_DIGEST.matcher(image.group(1)).find()) { + withoutDigest.add((line + 1) + ": " + lines.get(line).trim()); + } + } + unpinned.put(file, withoutDigest); + } + return unpinned; + } + + /** The first group the pattern captures in {@code text}; fails when it does not match. */ + private static String groupMatchedBy(Pattern pattern, String text) { + Matcher matcher = pattern.matcher(text); + assertThat(matcher.find()).as("%s in:%n%s", pattern, text).isTrue(); + return matcher.group(1); + } + + /** The shell words of the first group the pattern captures in {@code text}. */ + private static List wordsMatchedBy(Pattern pattern, String text) { + return shellWords(groupMatchedBy(pattern, text)); + } + + /** The lines a printf format prints, its {@code \n} written with one or more backslashes. */ + private static List printfLines(String format) { + return Pattern.compile("(?:\\\\+n|\\s)+") + .splitAsStream(format) + .filter(line -> !line.isEmpty()) + .toList(); + } + + /** The shell words of a step script, its backslash-newline continuations joined first. */ + private static List scriptWords(String run) { + return shellWords(run.replace("\\\n", " ")); + } + private static List shellWords(String arguments) { return Pattern.compile("\\s+") .splitAsStream(arguments.trim())