Skip to content

Commit e5b3514

Browse files
authored
fix(studio-server): publish waveform caches atomically (#3731)
* fix(studio-server): publish waveform caches atomically * fix(studio-server): reject linked waveform cache directories
1 parent 3874990 commit e5b3514

4 files changed

Lines changed: 329 additions & 13 deletions

File tree

‎.github/workflows/windows-render.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -474,6 +474,11 @@ jobs:
474474
# package scripts cannot oversubscribe the hosted Windows runner.
475475
run: bun run ${{ matrix.packages }} test -- --maxWorkers=2
476476

477+
- name: Verify waveform cache writes on Windows
478+
if: matrix.lane == 'studio-engine-cli'
479+
shell: pwsh
480+
run: bun run --cwd packages/studio-server test -- src/helpers/waveform.test.ts src/helpers/waveform.file-race.test.ts --maxWorkers=2
481+
477482
- name: Run runtime contract test
478483
if: matrix.runtime_contract
479484
shell: pwsh
Lines changed: 270 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,270 @@
1+
// @vitest-environment node
2+
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
3+
import { spawn } from "node:child_process";
4+
import { tmpdir } from "node:os";
5+
import { join } from "node:path";
6+
import { Hono } from "hono";
7+
import { buildWaveformCacheKey, generateWaveformCache } from "./waveform.js";
8+
import { registerWaveformRoutes } from "../routes/waveform.js";
9+
import type { StudioApiAdapter } from "../types.js";
10+
11+
const hooks = vi.hoisted(() => {
12+
const state: {
13+
decode?: () => void;
14+
writing?: () => void;
15+
failDecode: boolean;
16+
failWrite: boolean;
17+
failRename: boolean;
18+
failCleanup: boolean;
19+
} = { failDecode: false, failWrite: false, failRename: false, failCleanup: false };
20+
return state;
21+
});
22+
vi.mock("node:child_process", async () => {
23+
const { EventEmitter } = await import("node:events");
24+
return {
25+
spawn: vi.fn(() => {
26+
const proc = Object.assign(new EventEmitter(), { stdout: new EventEmitter() });
27+
queueMicrotask(() => {
28+
hooks.decode?.();
29+
if (!hooks.failDecode)
30+
proc.stdout.emit("data", Buffer.from(new Float32Array([0.5]).buffer));
31+
proc.emit("close", hooks.failDecode ? 1 : 0);
32+
});
33+
return proc;
34+
}),
35+
};
36+
});
37+
vi.mock("@hyperframes/parsers/ff-binaries", () => ({ findFfBinary: () => "ffmpeg" }));
38+
vi.mock("node:fs", async (importOriginal) => {
39+
const fs = await importOriginal<typeof import("node:fs")>();
40+
return {
41+
...fs,
42+
writeFileSync: (...args: Parameters<typeof fs.writeFileSync>) => {
43+
hooks.writing?.();
44+
if (hooks.failWrite) {
45+
fs.writeFileSync(args[0], "partial");
46+
throw new Error("cache write failed");
47+
}
48+
return fs.writeFileSync(...args);
49+
},
50+
rmSync: (...args: Parameters<typeof fs.rmSync>) => {
51+
if (hooks.failCleanup) throw new Error("cache cleanup failed");
52+
return fs.rmSync(...args);
53+
},
54+
renameSync: (...args: Parameters<typeof fs.renameSync>) => {
55+
if (hooks.failRename) throw new Error("cache rename failed");
56+
return fs.renameSync(...args);
57+
},
58+
};
59+
});
60+
const fs = await vi.importActual<typeof import("node:fs")>("node:fs");
61+
let projectDir: string;
62+
let cacheDir: string;
63+
let cachePath: string;
64+
let app: Hono;
65+
66+
beforeEach(() => {
67+
vi.clearAllMocks();
68+
Object.assign(hooks, {
69+
decode: undefined,
70+
writing: undefined,
71+
failDecode: false,
72+
failWrite: false,
73+
failRename: false,
74+
failCleanup: false,
75+
});
76+
projectDir = fs.mkdtempSync(join(tmpdir(), "hf-waveform-test-"));
77+
fs.writeFileSync(join(projectDir, "audio.wav"), "audio");
78+
cacheDir = join(projectDir, ".waveform-cache");
79+
cachePath = join(
80+
cacheDir,
81+
buildWaveformCacheKey("audio.wav", fs.statSync(join(projectDir, "audio.wav"))),
82+
);
83+
const adapter: StudioApiAdapter = {
84+
listProjects: () => [],
85+
resolveProject: (id) => (id === "demo" ? { id, dir: projectDir } : null),
86+
bundle: async () => null,
87+
lint: () => ({ findings: [] }),
88+
runtimeUrl: "/runtime.js",
89+
rendersDir: () => projectDir,
90+
startRender: () => ({ id: "unused", status: "rendering", progress: 0, outputPath: "unused" }),
91+
};
92+
app = new Hono();
93+
registerWaveformRoutes(app, adapter);
94+
});
95+
afterEach(() => fs.rmSync(projectDir, { recursive: true, force: true }));
96+
97+
function readPeaks() {
98+
return JSON.parse(fs.readFileSync(cachePath, "utf8"));
99+
}
100+
function seedCache(content: string) {
101+
fs.mkdirSync(cacheDir, { recursive: true });
102+
fs.writeFileSync(cachePath, content);
103+
}
104+
function request() {
105+
return app.request("http://localhost/projects/demo/waveform/audio.wav");
106+
}
107+
108+
for (const caller of ["helper", "route"]) {
109+
describe(caller, () => {
110+
async function generate() {
111+
if (caller === "helper") return generateWaveformCache(projectDir, "audio.wav");
112+
const response = await request();
113+
expect(response.status).toBe(200);
114+
expect(await response.json()).toEqual({ peaks: readPeaks() });
115+
}
116+
117+
it.each([true, false])(
118+
"does not write through a swapped cache symlink (target exists: %s)",
119+
async (exists) => {
120+
const target = join(projectDir, "outside.json");
121+
if (exists) fs.writeFileSync(target, "untouched");
122+
hooks.decode = () => {
123+
fs.mkdirSync(cacheDir, { recursive: true });
124+
fs.symlinkSync(target, cachePath, "file");
125+
};
126+
await generate();
127+
if (exists) expect(fs.readFileSync(target, "utf8")).toBe("untouched");
128+
else expect(fs.existsSync(target)).toBe(false);
129+
expect(fs.lstatSync(cachePath).isSymbolicLink()).toBe(false);
130+
expect(readPeaks()).toHaveLength(4000);
131+
expect(fs.readdirSync(cacheDir)).toEqual([
132+
buildWaveformCacheKey("audio.wav", fs.statSync(join(projectDir, "audio.wav"))),
133+
]);
134+
},
135+
);
136+
137+
it.each([true, false])(
138+
"rejects a cache-directory symlink (target exists: %s)",
139+
async (exists) => {
140+
const outside = fs.mkdtempSync(join(tmpdir(), "hf-waveform-outside-"));
141+
const target = join(outside, "cache");
142+
const outsideCache = join(
143+
target,
144+
buildWaveformCacheKey("audio.wav", fs.statSync(join(projectDir, "audio.wav"))),
145+
);
146+
if (exists) {
147+
fs.mkdirSync(target);
148+
fs.writeFileSync(outsideCache, "untouched");
149+
}
150+
fs.symlinkSync(target, cacheDir, process.platform === "win32" ? "junction" : "dir");
151+
try {
152+
if (caller === "helper")
153+
await expect(generateWaveformCache(projectDir, "audio.wav")).rejects.toThrow();
154+
else {
155+
const response = await request();
156+
expect(response.status).toBe(200);
157+
expect((await response.json()).peaks).toHaveLength(4000);
158+
}
159+
if (exists) {
160+
expect(fs.readFileSync(outsideCache, "utf8")).toBe("untouched");
161+
expect(fs.readdirSync(target)).toHaveLength(1);
162+
} else expect(fs.existsSync(target)).toBe(false);
163+
} finally {
164+
fs.rmSync(outside, { recursive: true, force: true });
165+
}
166+
},
167+
);
168+
169+
it("rejects a cache-directory symlink planted during decoding", async () => {
170+
const outside = fs.mkdtempSync(join(tmpdir(), "hf-waveform-outside-"));
171+
hooks.decode = () =>
172+
fs.symlinkSync(outside, cacheDir, process.platform === "win32" ? "junction" : "dir");
173+
try {
174+
if (caller === "helper")
175+
await expect(generateWaveformCache(projectDir, "audio.wav")).rejects.toThrow();
176+
else expect((await request()).status).toBe(200);
177+
expect(fs.readdirSync(outside)).toEqual([]);
178+
} finally {
179+
fs.rmSync(outside, { recursive: true, force: true });
180+
}
181+
});
182+
183+
it("reuses an existing cache without decoding", async () => {
184+
seedCache("[0.25,1]");
185+
await generate();
186+
expect(spawn).not.toHaveBeenCalled();
187+
expect(readPeaks()).toEqual([0.25, 1]);
188+
});
189+
190+
it("publishes complete JSON and removes staging directories", async () => {
191+
hooks.writing = () => expect(fs.existsSync(cachePath)).toBe(false);
192+
await generate();
193+
expect(readPeaks()).toHaveLength(4000);
194+
expect(fs.readdirSync(cacheDir)).toHaveLength(1);
195+
});
196+
197+
it.each(["write", "rename"])(
198+
"cleans up a failed %s and preserves the previous cache",
199+
async (failure) => {
200+
hooks.decode = () => seedCache("[0.25]");
201+
hooks.failWrite = failure === "write";
202+
hooks.failRename = failure === "rename";
203+
if (caller === "helper") {
204+
await expect(generateWaveformCache(projectDir, "audio.wav")).rejects.toThrow(
205+
`cache ${failure} failed`,
206+
);
207+
} else {
208+
const response = await request();
209+
expect(response.status).toBe(200);
210+
const body = await response.json();
211+
expect(body.peaks).toHaveLength(4000);
212+
}
213+
expect(readPeaks()).toEqual([0.25]);
214+
expect(fs.readdirSync(cacheDir)).toHaveLength(1);
215+
},
216+
);
217+
218+
it("handles a cache-directory creation failure with the existing error contract", async () => {
219+
fs.writeFileSync(cacheDir, "blocked");
220+
if (caller === "helper")
221+
await expect(generateWaveformCache(projectDir, "audio.wav")).rejects.toThrow();
222+
else expect((await request()).status).toBe(200);
223+
expect(fs.readFileSync(cacheDir, "utf8")).toBe("blocked");
224+
});
225+
});
226+
}
227+
228+
it("regenerates a corrupt cache and reuses the replacement", async () => {
229+
seedCache("not JSON");
230+
hooks.writing = () => expect(fs.readFileSync(cachePath, "utf8")).toBe("not JSON");
231+
expect((await request()).status).toBe(200);
232+
expect(readPeaks()).toHaveLength(4000);
233+
expect((await request()).status).toBe(200);
234+
expect(spawn).toHaveBeenCalledTimes(1);
235+
});
236+
it("concurrent misses leave one complete cache and no staging files", async () => {
237+
await Promise.all([generateWaveformCache(projectDir, "audio.wav"), request(), request()]);
238+
expect(readPeaks()).toHaveLength(4000);
239+
expect(fs.readdirSync(cacheDir)).toHaveLength(1);
240+
});
241+
it("keeps helper skipping, route 404s and decode failures unchanged", async () => {
242+
expect((await app.request("http://localhost/projects/missing/waveform/audio.wav")).status).toBe(
243+
404,
244+
);
245+
hooks.failDecode = true;
246+
await expect(generateWaveformCache(projectDir, "audio.wav")).rejects.toThrow(
247+
"ffmpeg exited with code 1",
248+
);
249+
const failed = await request();
250+
expect(failed.status).toBe(500);
251+
expect(await failed.json()).toEqual({ error: "failed to decode audio" });
252+
fs.unlinkSync(join(projectDir, "audio.wav"));
253+
await expect(generateWaveformCache(projectDir, "audio.wav")).resolves.toBeUndefined();
254+
expect((await request()).status).toBe(404);
255+
expect(fs.existsSync(cacheDir)).toBe(false);
256+
});
257+
258+
it("cleanup failure does not turn a successful publication into a helper error", async () => {
259+
hooks.failCleanup = true;
260+
await expect(generateWaveformCache(projectDir, "audio.wav")).resolves.toBeUndefined();
261+
expect(readPeaks()).toHaveLength(4000);
262+
});
263+
it("cleanup failure does not mask the original write error", async () => {
264+
hooks.failWrite = true;
265+
hooks.failCleanup = true;
266+
await expect(generateWaveformCache(projectDir, "audio.wav")).rejects.toThrow(
267+
"cache write failed",
268+
);
269+
expect(fs.existsSync(cachePath)).toBe(false);
270+
});

‎packages/studio-server/src/helpers/waveform.ts‎

Lines changed: 42 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,15 @@
11
import { spawn } from "node:child_process";
2-
import { existsSync, writeFileSync, mkdirSync, statSync } from "node:fs";
3-
import { join } from "node:path";
2+
import {
3+
existsSync,
4+
writeFileSync,
5+
mkdirSync,
6+
lstatSync,
7+
mkdtempSync,
8+
renameSync,
9+
rmSync,
10+
statSync,
11+
} from "node:fs";
12+
import { dirname, join } from "node:path";
413
import { findFfBinary } from "@hyperframes/parsers/ff-binaries";
514

615
const SAMPLE_RATE = 4000;
@@ -97,9 +106,37 @@ export async function generateWaveformCache(projectDir: string, assetPath: strin
97106
const stats = statSync(audioPath);
98107
const cacheDir = join(projectDir, ".waveform-cache");
99108
const cachePath = join(cacheDir, buildWaveformCacheKey(assetPath, stats));
100-
if (existsSync(cachePath)) return;
109+
if (isWaveformCacheDirectory(cacheDir) && existsSync(cachePath)) return;
101110

102111
const peaks = await decodeAudioPeaks(audioPath);
103-
mkdirSync(cacheDir, { recursive: true });
104-
writeFileSync(cachePath, JSON.stringify(peaks));
112+
writeWaveformCache(cachePath, peaks);
113+
}
114+
115+
export function isWaveformCacheDirectory(cacheDir: string): boolean {
116+
return lstatSync(cacheDir, { throwIfNoEntry: false })?.isDirectory() ?? false;
117+
}
118+
119+
/** Publish complete peaks without following a replaced cache-file symlink. */
120+
export function writeWaveformCache(cachePath: string, peaks: number[]): void {
121+
const cacheDir = dirname(cachePath);
122+
try {
123+
mkdirSync(cacheDir, { mode: 0o700 });
124+
} catch (error) {
125+
if (!(error instanceof Error && "code" in error && error.code === "EEXIST")) throw error;
126+
}
127+
if (!isWaveformCacheDirectory(cacheDir)) {
128+
throw new Error("Waveform cache must be a directory, not a symlink");
129+
}
130+
const stagingDir = mkdtempSync(join(cacheDir, ".waveform-"));
131+
try {
132+
const stagingPath = join(stagingDir, "peaks.json");
133+
writeFileSync(stagingPath, JSON.stringify(peaks), { flag: "wx" });
134+
renameSync(stagingPath, cachePath);
135+
} finally {
136+
try {
137+
rmSync(stagingDir, { recursive: true, force: true });
138+
} catch {
139+
// Cleanup must not mask a write error or fail an already published cache.
140+
}
141+
}
105142
}

‎packages/studio-server/src/routes/waveform.ts‎

Lines changed: 12 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,13 @@
1-
import { existsSync, readFileSync, writeFileSync, mkdirSync, statSync } from "node:fs";
1+
import { existsSync, readFileSync, statSync } from "node:fs";
22
import { join } from "node:path";
33
import type { Hono } from "hono";
44
import type { StudioApiAdapter } from "../types.js";
5-
import { decodeAudioPeaks, buildWaveformCacheKey } from "../helpers/waveform.js";
5+
import {
6+
decodeAudioPeaks,
7+
buildWaveformCacheKey,
8+
writeWaveformCache,
9+
isWaveformCacheDirectory,
10+
} from "../helpers/waveform.js";
611

712
export function registerWaveformRoutes(api: Hono, adapter: StudioApiAdapter): void {
813
api.get("/projects/:id/waveform/*", async (c) => {
@@ -21,13 +26,13 @@ export function registerWaveformRoutes(api: Hono, adapter: StudioApiAdapter): vo
2126
// asset in place invalidates its peaks instead of drawing the old ones.
2227
const cachePath = join(cacheDir, buildWaveformCacheKey(assetPath, stats));
2328

24-
if (existsSync(cachePath)) {
25-
try {
29+
try {
30+
if (isWaveformCacheDirectory(cacheDir) && existsSync(cachePath)) {
2631
const peaks = JSON.parse(readFileSync(cachePath, "utf-8")) as number[];
2732
return c.json({ peaks });
28-
} catch {
29-
// corrupt cache — regenerate
3033
}
34+
} catch {
35+
// corrupt or inaccessible cache — regenerate
3136
}
3237

3338
let peaks: number[];
@@ -38,8 +43,7 @@ export function registerWaveformRoutes(api: Hono, adapter: StudioApiAdapter): vo
3843
}
3944

4045
try {
41-
mkdirSync(cacheDir, { recursive: true });
42-
writeFileSync(cachePath, JSON.stringify(peaks));
46+
writeWaveformCache(cachePath, peaks);
4347
} catch {
4448
// cache write failure is non-fatal
4549
}

0 commit comments

Comments
 (0)