Skip to content

Commit 1fd5fe7

Browse files
committed
fix(render): publish artifacts atomically
1 parent cb69d3f commit 1fd5fe7

3 files changed

Lines changed: 411 additions & 9 deletions

File tree

Lines changed: 202 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,202 @@
1+
import { describe, expect, it } from "vitest";
2+
import {
3+
existsSync,
4+
lstatSync,
5+
mkdirSync,
6+
mkdtempSync,
7+
readFileSync,
8+
readdirSync,
9+
renameSync as renamePathSync,
10+
rmSync,
11+
writeFileSync,
12+
} from "node:fs";
13+
import { dirname, join } from "node:path";
14+
import { tmpdir } from "node:os";
15+
import { ArtifactTransaction } from "./artifactTransaction.js";
16+
17+
function tempDir(): string {
18+
return mkdtempSync(join(tmpdir(), "hf-artifact-transaction-"));
19+
}
20+
21+
function transactionDirectories(dir: string): string[] {
22+
return readdirSync(dir).filter((name) => name.includes(".hf-transaction-"));
23+
}
24+
25+
describe("ArtifactTransaction", () => {
26+
it("uses a private, atomically reserved sibling directory", () => {
27+
const dir = tempDir();
28+
const destination = join(dir, "render.mp4");
29+
const transaction = new ArtifactTransaction(destination, "file");
30+
const transactionDir = dirname(transaction.stagingPath);
31+
32+
expect(dirname(transactionDir)).toBe(dir);
33+
expect(transaction.stagingPath).toBe(join(transactionDir, "render.mp4"));
34+
if (process.platform !== "win32") {
35+
expect(lstatSync(transactionDir).mode & 0o777).toBe(0o700);
36+
}
37+
38+
transaction.rollback();
39+
expect(transactionDirectories(dir)).toEqual([]);
40+
});
41+
42+
it("atomically replaces a file only after validation", () => {
43+
const dir = tempDir();
44+
const destination = join(dir, "render.mp4");
45+
writeFileSync(destination, "existing");
46+
const transaction = new ArtifactTransaction(destination, "file");
47+
writeFileSync(transaction.stagingPath, "new-render");
48+
49+
transaction.commit();
50+
51+
expect(readFileSync(destination, "utf8")).toBe("new-render");
52+
expect(existsSync(transaction.stagingPath)).toBe(false);
53+
expect(transactionDirectories(dir)).toEqual([]);
54+
});
55+
56+
it("leaves an existing file byte-identical when validation fails", () => {
57+
const dir = tempDir();
58+
const destination = join(dir, "render.gif");
59+
const existing = Buffer.from([0, 1, 2, 3, 255]);
60+
writeFileSync(destination, existing);
61+
const transaction = new ArtifactTransaction(destination, "file");
62+
writeFileSync(transaction.stagingPath, "");
63+
64+
expect(() => transaction.commit()).toThrow("not a non-empty file");
65+
transaction.rollback();
66+
67+
expect(readFileSync(destination)).toEqual(existing);
68+
expect(existsSync(transaction.stagingPath)).toBe(false);
69+
expect(transactionDirectories(dir)).toEqual([]);
70+
});
71+
72+
it("keeps the existing file addressable when atomic promotion fails", () => {
73+
const dir = tempDir();
74+
const destination = join(dir, "render.mp4");
75+
writeFileSync(destination, "existing");
76+
let replacementCalls = 0;
77+
const transaction = new ArtifactTransaction(destination, "file", {
78+
existsSync,
79+
renameSync(source, target) {
80+
replacementCalls += 1;
81+
expect(source).toBe(transaction.stagingPath);
82+
expect(target).toBe(destination);
83+
expect(readFileSync(destination, "utf8")).toBe("existing");
84+
throw new Error("injected replacement failure");
85+
},
86+
rmSync,
87+
});
88+
writeFileSync(transaction.stagingPath, "new-render");
89+
90+
expect(() => transaction.commit()).toThrow("injected replacement failure");
91+
expect(replacementCalls).toBe(1);
92+
expect(readFileSync(destination, "utf8")).toBe("existing");
93+
94+
transaction.rollback();
95+
expect(existsSync(transaction.stagingPath)).toBe(false);
96+
expect(transactionDirectories(dir)).toEqual([]);
97+
});
98+
99+
it("removes cancelled staging output without touching the destination", () => {
100+
const dir = tempDir();
101+
const destination = join(dir, "render.mp4");
102+
writeFileSync(destination, "keep-me");
103+
const transaction = new ArtifactTransaction(destination, "file");
104+
writeFileSync(transaction.stagingPath, "partial-render");
105+
106+
transaction.rollback();
107+
108+
expect(readFileSync(destination, "utf8")).toBe("keep-me");
109+
expect(existsSync(transaction.stagingPath)).toBe(false);
110+
expect(transactionDirectories(dir)).toEqual([]);
111+
});
112+
113+
it("promotes a validated PNG sequence as one directory artifact", () => {
114+
const dir = tempDir();
115+
const destination = join(dir, "frames");
116+
mkdirSync(destination);
117+
writeFileSync(join(destination, "frame_000001.png"), "old");
118+
const transaction = new ArtifactTransaction(destination, "directory");
119+
mkdirSync(transaction.stagingPath);
120+
writeFileSync(join(transaction.stagingPath, "frame_000001.png"), "png-1");
121+
writeFileSync(join(transaction.stagingPath, "frame_000002.png"), "png-2");
122+
123+
transaction.commit();
124+
125+
expect(readdirSync(destination).sort()).toEqual(["frame_000001.png", "frame_000002.png"]);
126+
expect(readFileSync(join(destination, "frame_000001.png"), "utf8")).toBe("png-1");
127+
expect(transactionDirectories(dir)).toEqual([]);
128+
});
129+
130+
it("restores the previous PNG sequence when directory promotion fails", () => {
131+
const dir = tempDir();
132+
const destination = join(dir, "frames");
133+
mkdirSync(destination);
134+
writeFileSync(join(destination, "frame_000001.png"), "existing-frame");
135+
let transaction: ArtifactTransaction;
136+
transaction = new ArtifactTransaction(destination, "directory", {
137+
existsSync,
138+
renameSync(source, target) {
139+
if (source === transaction.stagingPath && target === destination) {
140+
throw new Error("injected directory promotion failure");
141+
}
142+
renamePathSync(source, target);
143+
},
144+
rmSync,
145+
});
146+
mkdirSync(transaction.stagingPath);
147+
writeFileSync(join(transaction.stagingPath, "frame_000001.png"), "new-frame");
148+
149+
expect(() => transaction.commit()).toThrow("injected directory promotion failure");
150+
151+
expect(readFileSync(join(destination, "frame_000001.png"), "utf8")).toBe("existing-frame");
152+
expect(transactionDirectories(dir)).toEqual([]);
153+
});
154+
155+
it("does not delete a concurrent PNG sequence published during recovery", () => {
156+
const dir = tempDir();
157+
const destination = join(dir, "frames");
158+
mkdirSync(destination);
159+
writeFileSync(join(destination, "frame_000001.png"), "existing-frame");
160+
const concurrentTransaction = new ArtifactTransaction(destination, "directory");
161+
mkdirSync(concurrentTransaction.stagingPath);
162+
writeFileSync(join(concurrentTransaction.stagingPath, "frame_000001.png"), "concurrent-frame");
163+
164+
let firstTransaction: ArtifactTransaction;
165+
firstTransaction = new ArtifactTransaction(destination, "directory", {
166+
existsSync,
167+
renameSync(source, target) {
168+
if (source === firstTransaction.stagingPath && target === destination) {
169+
concurrentTransaction.commit();
170+
expect(readFileSync(join(destination, "frame_000001.png"), "utf8")).toBe(
171+
"concurrent-frame",
172+
);
173+
throw new Error("injected first promotion failure");
174+
}
175+
renamePathSync(source, target);
176+
},
177+
rmSync,
178+
});
179+
mkdirSync(firstTransaction.stagingPath);
180+
writeFileSync(join(firstTransaction.stagingPath, "frame_000001.png"), "first-frame");
181+
182+
expect(() => firstTransaction.commit()).toThrow("injected first promotion failure");
183+
184+
expect(readFileSync(join(destination, "frame_000001.png"), "utf8")).toBe("concurrent-frame");
185+
expect(transactionDirectories(dir)).toEqual([]);
186+
});
187+
188+
it("rejects an empty PNG sequence and preserves the existing directory", () => {
189+
const dir = tempDir();
190+
const destination = join(dir, "frames");
191+
mkdirSync(destination);
192+
writeFileSync(join(destination, "frame_000001.png"), "existing-frame");
193+
const transaction = new ArtifactTransaction(destination, "directory");
194+
mkdirSync(transaction.stagingPath);
195+
196+
expect(() => transaction.commit()).toThrow("directory is empty");
197+
transaction.rollback();
198+
199+
expect(readFileSync(join(destination, "frame_000001.png"), "utf8")).toBe("existing-frame");
200+
expect(transactionDirectories(dir)).toEqual([]);
201+
});
202+
});
Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
import {
2+
closeSync,
3+
existsSync,
4+
fstatSync,
5+
mkdtempSync,
6+
openSync,
7+
readSync,
8+
readdirSync,
9+
renameSync,
10+
rmSync,
11+
} from "node:fs";
12+
import { basename, dirname, extname, join, resolve } from "node:path";
13+
14+
export type ArtifactKind = "file" | "directory";
15+
16+
export interface ArtifactTransactionFileSystem {
17+
existsSync(path: string): boolean;
18+
renameSync(source: string, destination: string): void;
19+
rmSync(path: string, options: { recursive: true; force: true }): void;
20+
}
21+
22+
const defaultFileSystem: ArtifactTransactionFileSystem = {
23+
existsSync,
24+
renameSync,
25+
rmSync,
26+
};
27+
28+
function createSiblingTransactionDirectory(destination: string): string {
29+
const parent = dirname(destination);
30+
const extension = extname(destination);
31+
const stem = extension ? basename(destination, extension) : basename(destination);
32+
// mkdtemp reserves the directory atomically and creates it with private
33+
// permissions. Keeping it beside the destination preserves same-filesystem
34+
// rename semantics without exposing predictable files in a shared temp dir.
35+
return mkdtempSync(join(parent, `.${stem}.hf-transaction-`));
36+
}
37+
38+
function assertReadableNonEmptyFile(path: string): void {
39+
// Validate the opened object, not a pathname checked before opening it.
40+
// The descriptor pins the file across validation and closes the TOCTOU gap
41+
// between lstat(path) and open(path).
42+
const fd = openSync(path, "r");
43+
try {
44+
const stat = fstatSync(fd);
45+
if (!stat.isFile() || stat.size <= 0) {
46+
throw new Error(`Render artifact is not a non-empty file: ${path}`);
47+
}
48+
readSync(fd, Buffer.allocUnsafe(1), 0, 1, 0);
49+
} finally {
50+
closeSync(fd);
51+
}
52+
}
53+
54+
function collectDirectoryFiles(root: string): string[] {
55+
const files: string[] = [];
56+
const visit = (directory: string): void => {
57+
for (const entry of readdirSync(directory, { withFileTypes: true })) {
58+
const path = join(directory, entry.name);
59+
if (entry.isDirectory()) visit(path);
60+
else if (entry.isFile()) files.push(path);
61+
}
62+
};
63+
visit(root);
64+
return files;
65+
}
66+
67+
/**
68+
* Stages a render beside its final destination and promotes only a validated
69+
* artifact. File promotion uses one atomic replacement rename, so an existing
70+
* file remains addressable until the new file replaces it. Replacing a
71+
* non-empty directory cannot be expressed as one portable rename; that case
72+
* uses a recoverable backup handoff while preserving the previous contents on
73+
* ordinary failures.
74+
*/
75+
export class ArtifactTransaction {
76+
readonly destinationPath: string;
77+
readonly stagingPath: string;
78+
private readonly transactionDirectory: string;
79+
private readonly backupPath: string;
80+
private state: "active" | "committed" | "rolled-back" = "active";
81+
82+
constructor(
83+
destinationPath: string,
84+
private readonly kind: ArtifactKind,
85+
private readonly fileSystem: ArtifactTransactionFileSystem = defaultFileSystem,
86+
) {
87+
this.destinationPath = resolve(destinationPath);
88+
this.transactionDirectory = createSiblingTransactionDirectory(this.destinationPath);
89+
this.stagingPath = join(this.transactionDirectory, basename(this.destinationPath));
90+
this.backupPath = join(this.transactionDirectory, "backup");
91+
}
92+
93+
validate(): void {
94+
if (this.kind === "file") {
95+
assertReadableNonEmptyFile(this.stagingPath);
96+
return;
97+
}
98+
let files: string[];
99+
try {
100+
files = collectDirectoryFiles(this.stagingPath);
101+
} catch (error) {
102+
throw new Error(`Render artifact is not a readable directory: ${this.stagingPath}`, {
103+
cause: error,
104+
});
105+
}
106+
if (files.length === 0) {
107+
throw new Error(`Render artifact directory is empty: ${this.stagingPath}`);
108+
}
109+
for (const file of files) assertReadableNonEmptyFile(file);
110+
}
111+
112+
commit(): void {
113+
if (this.state !== "active") {
114+
throw new Error(`Cannot commit an artifact transaction in state ${this.state}`);
115+
}
116+
this.validate();
117+
const hadDestination = this.fileSystem.existsSync(this.destinationPath);
118+
119+
// Both files and new directories publish with one rename. In particular,
120+
// do not move an existing file out of the way first: rename replaces it
121+
// atomically, so readers see either the complete old file or the complete
122+
// new file and a failed rename leaves the old file untouched.
123+
if (this.kind === "file" || !hadDestination) {
124+
this.fileSystem.renameSync(this.stagingPath, this.destinationPath);
125+
this.state = "committed";
126+
this.cleanupTransactionDirectory();
127+
return;
128+
}
129+
130+
// Portable Node filesystem APIs cannot atomically replace a non-empty
131+
// directory. Keep the backup handoff for an existing PNG-sequence output;
132+
// it provides recovery on ordinary errors, but not atomic visibility or
133+
// crash recovery. Callers should publish directory outputs to a fresh path
134+
// when they require the same visibility guarantee as file artifacts.
135+
this.fileSystem.renameSync(this.destinationPath, this.backupPath);
136+
try {
137+
this.fileSystem.renameSync(this.stagingPath, this.destinationPath);
138+
this.state = "committed";
139+
} catch (error) {
140+
// A competing transaction may have published while this destination was
141+
// temporarily vacant. Never remove that caller-visible directory: only
142+
// restore our backup while the destination remains unclaimed.
143+
this.restoreBackupIfDestinationUnclaimed();
144+
this.state = "rolled-back";
145+
this.cleanupTransactionDirectory();
146+
throw error;
147+
}
148+
// Promotion succeeded. Cleanup is best-effort: a stale private transaction
149+
// directory is safer than reporting failure after publishing the artifact.
150+
this.cleanupTransactionDirectory();
151+
}
152+
153+
rollback(): void {
154+
if (this.state !== "active") return;
155+
this.fileSystem.rmSync(this.stagingPath, { recursive: true, force: true });
156+
if (
157+
this.fileSystem.existsSync(this.backupPath) &&
158+
!this.fileSystem.existsSync(this.destinationPath)
159+
) {
160+
this.fileSystem.renameSync(this.backupPath, this.destinationPath);
161+
}
162+
this.cleanupTransactionDirectory();
163+
this.state = "rolled-back";
164+
}
165+
166+
private restoreBackupIfDestinationUnclaimed(): void {
167+
if (
168+
!this.fileSystem.existsSync(this.backupPath) ||
169+
this.fileSystem.existsSync(this.destinationPath)
170+
) {
171+
return;
172+
}
173+
try {
174+
this.fileSystem.renameSync(this.backupPath, this.destinationPath);
175+
} catch (error) {
176+
// Losing the rename race to a concurrent publisher is successful
177+
// recovery: its complete artifact owns the destination. Propagate other
178+
// restore failures so the caller can retry rollback with the backup kept.
179+
if (!this.fileSystem.existsSync(this.destinationPath)) throw error;
180+
}
181+
}
182+
183+
private cleanupTransactionDirectory(): void {
184+
try {
185+
this.fileSystem.rmSync(this.transactionDirectory, { recursive: true, force: true });
186+
} catch {
187+
// Never turn a successfully published artifact into a failed render just
188+
// because best-effort cleanup of its private transaction directory failed.
189+
}
190+
}
191+
}

0 commit comments

Comments
 (0)