|
| 1 | +/** |
| 2 | + * Tier WXP — what an export leaves on disk when a step fails. |
| 3 | + * |
| 4 | + * Publication and cleanup are filesystem races. Neither reproduces by waiting, |
| 5 | + * so each is made to fail through the operations `exportArtifact` accepts — |
| 6 | + * plain functions, defaulting to the real ones, passed in rather than resolved |
| 7 | + * through a name anything could rebind. |
| 8 | + * |
| 9 | + * Every case records which of those operations were actually reached and |
| 10 | + * asserts that first. An export that refused early leaves no target and no |
| 11 | + * staging state too, so filesystem state on its own says nothing about whether |
| 12 | + * publication was ever attempted: a suite that only looked at the directory |
| 13 | + * would pass against a build where export never got that far. |
| 14 | + */ |
| 15 | + |
| 16 | +import { describe, it } from "@executablemd/test-support/bdd"; |
| 17 | +import { expect } from "@executablemd/test-support/expect"; |
| 18 | +import { ensureDir, exists, readdir, readTextFile, rm, writeTextFile } from "@effectionx/fs"; |
| 19 | +import { exec } from "@effectionx/process"; |
| 20 | +import { ensure, type Operation, scoped, until } from "effection"; |
| 21 | +import { randomUUID } from "node:crypto"; |
| 22 | +import { link } from "node:fs/promises"; |
| 23 | +import process from "node:process"; |
| 24 | +import { join } from "node:path"; |
| 25 | +import { tmpdir } from "node:os"; |
| 26 | +import { fileURLToPath } from "node:url"; |
| 27 | +import { runCli } from "@executablemd/test-support/launch"; |
| 28 | +import { useWorkflowLifecycle, useWorkflowRunStorage } from "@executablemd/workflow/deno"; |
| 29 | +import { exportArtifact, type ExportFilesystem } from "../src/workflow-management.ts"; |
| 30 | +import { readDefinitionSource } from "../src/workflow-source.ts"; |
| 31 | + |
| 32 | +const RELEASE = ["# Release", "", "nothing to see here", ""].join("\n"); |
| 33 | +const CLI = fileURLToPath(new URL("../src/cli.ts", import.meta.url)); |
| 34 | + |
| 35 | +interface Fixture { |
| 36 | + readonly repository: string; |
| 37 | + readonly runs: string; |
| 38 | + readonly home: string; |
| 39 | +} |
| 40 | + |
| 41 | +function* git(repository: string, args: string[]): Operation<void> { |
| 42 | + const result = yield* exec("git", { arguments: args, cwd: repository }).expect(); |
| 43 | + if (result.code !== 0) { |
| 44 | + throw new Error(`git ${args.join(" ")} failed: ${result.stderr}`); |
| 45 | + } |
| 46 | +} |
| 47 | + |
| 48 | +/** |
| 49 | + * A committed repository with one completed run in it. |
| 50 | + * |
| 51 | + * Started through the real CLI, so what these tests export is a run some |
| 52 | + * execution actually produced rather than rows a fixture wrote. |
| 53 | + */ |
| 54 | +function useExportedRun<T>(body: (fixture: Fixture) => Operation<T>): Operation<T> { |
| 55 | + return scoped(function* () { |
| 56 | + const root = join(tmpdir(), `xmd-wxp-${randomUUID()}`); |
| 57 | + const fixture: Fixture = { |
| 58 | + repository: join(root, "repository"), |
| 59 | + runs: join(root, "runs"), |
| 60 | + home: join(root, "home"), |
| 61 | + }; |
| 62 | + yield* ensure(() => rm(root, { recursive: true, force: true })); |
| 63 | + yield* ensureDir(join(fixture.repository, "flows")); |
| 64 | + yield* ensureDir(fixture.home); |
| 65 | + yield* writeTextFile(join(fixture.repository, "flows/release.md"), RELEASE); |
| 66 | + |
| 67 | + yield* git(fixture.repository, ["init", "-q", "--initial-branch=main", "."]); |
| 68 | + yield* git(fixture.repository, ["config", "user.email", "[email protected]"]); |
| 69 | + yield* git(fixture.repository, ["config", "user.name", "Tier WXP"]); |
| 70 | + yield* git(fixture.repository, ["add", "-A"]); |
| 71 | + yield* git(fixture.repository, [ |
| 72 | + "-c", |
| 73 | + "commit.gpgsign=false", |
| 74 | + "commit", |
| 75 | + "-q", |
| 76 | + "-m", |
| 77 | + "definition", |
| 78 | + ]); |
| 79 | + |
| 80 | + const started = yield* runCli(["workflow", "start", "--id=release-1", "flows/release.md"], { |
| 81 | + cwd: fixture.repository, |
| 82 | + env: { HOME: fixture.home, XMD_WORKFLOW_RUNS: fixture.runs }, |
| 83 | + }).join(); |
| 84 | + if (started.code !== 0) { |
| 85 | + throw new Error(`the fixture run did not start: ${started.stderr}`); |
| 86 | + } |
| 87 | + // Named here rather than discovered as an empty export later: a fixture |
| 88 | + // whose run landed somewhere else would make every case below refuse for a |
| 89 | + // reason that has nothing to do with what it is testing. |
| 90 | + const stored = yield* readdir(fixture.runs); |
| 91 | + if (stored.length === 0) { |
| 92 | + throw new Error(`the fixture run was not stored under ${fixture.runs}: ${started.stderr}`); |
| 93 | + } |
| 94 | + |
| 95 | + return yield* body(fixture); |
| 96 | + }); |
| 97 | +} |
| 98 | + |
| 99 | +/** |
| 100 | + * The host this package installs, pointed at the fixture's runs. |
| 101 | + * |
| 102 | + * Run from inside the repository, because reading a retained definition back |
| 103 | + * means opening the checkout that run recorded. |
| 104 | + */ |
| 105 | +function withHost<T>(fixture: Fixture, body: () => Operation<T>): Operation<T> { |
| 106 | + return scoped(function* () { |
| 107 | + const previous = process.cwd(); |
| 108 | + process.chdir(fixture.repository); |
| 109 | + yield* ensure(() => { |
| 110 | + process.chdir(previous); |
| 111 | + }); |
| 112 | + yield* useWorkflowRunStorage({ root: fixture.runs }); |
| 113 | + yield* useWorkflowLifecycle({ root: fixture.runs, definitionSource: readDefinitionSource }); |
| 114 | + return yield* body(); |
| 115 | + }); |
| 116 | +} |
| 117 | + |
| 118 | +/** The real operations, each recording that it was reached. */ |
| 119 | +function recording(overrides: Partial<ExportFilesystem> = {}): { |
| 120 | + readonly log: string[]; |
| 121 | + readonly filesystem: ExportFilesystem; |
| 122 | +} { |
| 123 | + const log: string[] = []; |
| 124 | + const real: ExportFilesystem = { |
| 125 | + *link(staging: string, output: string): Operation<void> { |
| 126 | + log.push("link"); |
| 127 | + yield* until(link(staging, output)); |
| 128 | + }, |
| 129 | + *remove(directory: string): Operation<void> { |
| 130 | + log.push("remove"); |
| 131 | + yield* rm(directory, { recursive: true, force: true }); |
| 132 | + }, |
| 133 | + *unlink(target: string): Operation<void> { |
| 134 | + log.push("unlink"); |
| 135 | + yield* rm(target, { force: true }); |
| 136 | + }, |
| 137 | + }; |
| 138 | + const filesystem: ExportFilesystem = { ...real }; |
| 139 | + for (const step of Object.keys(overrides) as (keyof ExportFilesystem)[]) { |
| 140 | + const replacement = overrides[step]; |
| 141 | + if (replacement !== undefined) { |
| 142 | + Object.defineProperty(filesystem, step, { |
| 143 | + value: function* (...args: [string, string]): Operation<void> { |
| 144 | + log.push(step); |
| 145 | + yield* replacement(...args); |
| 146 | + }, |
| 147 | + enumerable: true, |
| 148 | + }); |
| 149 | + } |
| 150 | + } |
| 151 | + return { log, filesystem }; |
| 152 | +} |
| 153 | + |
| 154 | +/** Whatever staging the export could have left in the publishing directory. */ |
| 155 | +function* leftovers(fixture: Fixture): Operation<string[]> { |
| 156 | + return (yield* readdir(fixture.repository)).filter((name) => name.startsWith(".xmd-export-")); |
| 157 | +} |
| 158 | + |
| 159 | +describe("Tier WXP — what an export leaves behind", () => { |
| 160 | + it("WXP1: a racing target is refused by link and survives byte-identical", function* () { |
| 161 | + yield* useExportedRun(function* (fixture) { |
| 162 | + const target = join(fixture.repository, "raced.xmd"); |
| 163 | + const racer = "somebody else got here first\n"; |
| 164 | + |
| 165 | + const recorder = recording({ |
| 166 | + // The name is taken between validation and publication. The real link |
| 167 | + // then refuses, which is the whole reason publication uses one. |
| 168 | + *link(staging: string, output: string): Operation<void> { |
| 169 | + yield* writeTextFile(output, racer); |
| 170 | + yield* until(link(staging, output)); |
| 171 | + }, |
| 172 | + }); |
| 173 | + const outcome = yield* withHost(fixture, function* () { |
| 174 | + return yield* exportArtifact("release-1", target, recorder.filesystem); |
| 175 | + }); |
| 176 | + |
| 177 | + // Reached publication: without this the assertions below would pass |
| 178 | + // against an export that refused long before it got here. |
| 179 | + expect(recorder.log).toContain("link"); |
| 180 | + expect(outcome.exitCode).toBe(1); |
| 181 | + expect(yield* readTextFile(target)).toBe(racer); |
| 182 | + expect(yield* leftovers(fixture)).toEqual([]); |
| 183 | + }); |
| 184 | + }); |
| 185 | + |
| 186 | + it("WXP2: a publication failure reports nothing and removes staging", function* () { |
| 187 | + yield* useExportedRun(function* (fixture) { |
| 188 | + const target = join(fixture.repository, "unpublished.xmd"); |
| 189 | + |
| 190 | + const recorder = recording({ |
| 191 | + // deno-lint-ignore require-yield |
| 192 | + *link(): Operation<void> { |
| 193 | + throw new Error("the link step was made to fail"); |
| 194 | + }, |
| 195 | + }); |
| 196 | + const outcome = yield* withHost(fixture, function* () { |
| 197 | + return yield* exportArtifact("release-1", target, recorder.filesystem); |
| 198 | + }); |
| 199 | + |
| 200 | + expect(recorder.log).toEqual(["link"]); |
| 201 | + expect(outcome.exitCode).toBe(1); |
| 202 | + expect(yield* exists(target)).toBe(false); |
| 203 | + expect(yield* leftovers(fixture)).toEqual([]); |
| 204 | + }); |
| 205 | + }); |
| 206 | + |
| 207 | + it("WXP3: a cleanup failure rolls the published target back", function* () { |
| 208 | + yield* useExportedRun(function* (fixture) { |
| 209 | + const target = join(fixture.repository, "uncleaned.xmd"); |
| 210 | + |
| 211 | + const recorder = recording({ |
| 212 | + // deno-lint-ignore require-yield |
| 213 | + *remove(): Operation<void> { |
| 214 | + throw new Error("the remove step was made to fail"); |
| 215 | + }, |
| 216 | + }); |
| 217 | + const outcome = yield* withHost(fixture, function* () { |
| 218 | + return yield* exportArtifact("release-1", target, recorder.filesystem); |
| 219 | + }); |
| 220 | + |
| 221 | + // The order is the claim: the artifact really was published, cleanup |
| 222 | + // really did fail, and the target really was taken back afterwards. |
| 223 | + expect(recorder.log).toEqual(["link", "remove", "unlink"]); |
| 224 | + expect(outcome.exitCode).toBe(1); |
| 225 | + expect(yield* exists(target)).toBe(false); |
| 226 | + }); |
| 227 | + }); |
| 228 | + |
| 229 | + it("WXP4: a cancellation after staging leaves neither target nor staging", function* () { |
| 230 | + yield* useExportedRun(function* (fixture) { |
| 231 | + const target = join(fixture.repository, "cancelled.xmd"); |
| 232 | + const staged: string[] = []; |
| 233 | + |
| 234 | + const recorder = recording({ |
| 235 | + *link(_staging: string, _output: string): Operation<void> { |
| 236 | + // Staging exists by now: record what is on disk, then end the export |
| 237 | + // the way a cancellation ends it — without publishing. |
| 238 | + staged.push(...(yield* leftovers(fixture))); |
| 239 | + throw new Error("cancelled before publication completed"); |
| 240 | + }, |
| 241 | + }); |
| 242 | + const outcome = yield* withHost(fixture, function* () { |
| 243 | + return yield* exportArtifact("release-1", target, recorder.filesystem); |
| 244 | + }); |
| 245 | + |
| 246 | + // Staging was really there when the export was interrupted, and the |
| 247 | + // scope that owned it removed it on the way out. |
| 248 | + expect(recorder.log).toEqual(["link"]); |
| 249 | + expect(staged.length).toBe(1); |
| 250 | + expect(outcome.exitCode).toBe(1); |
| 251 | + expect(yield* exists(target)).toBe(false); |
| 252 | + expect(yield* leftovers(fixture)).toEqual([]); |
| 253 | + }); |
| 254 | + }); |
| 255 | +}); |
0 commit comments